#Filename placeholders

Rspack's filename-related options support placeholders. This lets you generate output filenames dynamically based on the current build context. It helps distinguish different assets and improves caching efficiency.

Different options support different types of placeholders. This page lists all placeholder types available in Rspack, and which filename options use which placeholder type.

#Example

For example, the [contenthash] placeholder generates a hash based on the file content. If the content does not change, the filename remains stable. This is ideal for long-term caching.

Here is an example showing how [name] and [contenthash] can be used in output.filename:

const isProd = process.env.NODE_ENV === 'production';

export default {
  entry: {
    main: './src/main.js',
    list: './src/list.js',
  },
  output: {
    filename: isProd ? '[name].[contenthash].js' : '[name].js',
  },
};

This outputs:

src/
├── main.js
└── list.js
dist/
├── main.abcdefghabcdefgh.js
└── list.qwertyuiqwertyui.js

#Filename options

The following table summarizes common filename options and the placeholder types they support:

#Placeholder types

#Compilation placeholders

Compilation placeholders expose information about the entire build process.

#Chunk placeholders

Chunk placeholders expose information about a specific chunk.

#Module placeholders

Module placeholders expose information about a specific module.

#File placeholders

File placeholders expose information derived from the file path.

Relationships:

• [file] equals [path][base]
• [base] equals [name][ext]

A complete path can be built using any of these forms:

• [path][name][ext][query][fragment]
• [path][base][query][fragment]
• [file][query][fragment]

#URL placeholders

URL placeholders expose information about the current request URL.

#Hash Length

Hash placeholders ([hash], [contenthash], [chunkhash]) support length modifiers using [hash:n], where the default length is 16.

Example truncating [contenthash] to 8 characters:

const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: isProd ? '[name].[contenthash:8].js' : '[name].js',
  },
};

You can also specify a digest (only base64 is supported) and length:

const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: isProd ? '[name].[contenthash:base64:8].js' : '[name].js',
  },
};

Alternatively, you can configure a global default using output.hashDigestLength.

#Escaping Placeholders

If you want to preserve the literal placeholder text instead of having Rspack interpolate it, escape the brackets with backslashes.

For example, to include [name] in the filename, rather than interpolating it as the chunk name, you can escape it with backslashes:

export default {
  output: {
    filename: '\\[name\\].js',
  },
};

#Using functions

Some options allow specifying a function instead of a string.

For example, output.filename option accepts a function, which will be called during compilation and receives a PathData object containing contextual information.

export default {
  output: {
    filename: pathData => {
      return pathData.chunk.name === 'main' ? '[name].js' : '[name]/[name].js';
    },
  },
};

The function is invoked during the build process and receives an object that contains the current context data. You can use this information to construct any string you need, and the returned string will still go through the same placeholder substitution rules.

type PathData = {
  filename?: string;
  hash?: string;
  contentHash?: string;
  runtime?: string;
  url?: string;
  id?: string;
  chunk?: Chunk | ChunkPathData;
  contentHashType?: string;
};

type ChunkPathData = {
  id?: string;
  name?: string;
  hash?: string;
  contentHash?: Record<string, string>;
};