close
Guide
Config
Plugin
API
Community
Guide
Config
Plugin
API
Community

output.filename

  • Type:
type FilenameConfig = {
  js?:
    | string
    | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
  css?: string;
  svg?: string;
  font?: string;
  image?: string;
  media?: string;
};
  • Default:
// Development
const devDefaultFilename = {
  js: '[name].js',
  css: '[name].css',
  svg: '[name].[contenthash:8].svg',
  font: '[name].[contenthash:8][ext]',
  image: '[name].[contenthash:8][ext]',
  media: '[name].[contenthash:8][ext]',
};

// Production
const prodDefaultFilename = {
  js: isServer ? '[name].js' : '[name].[contenthash:8].js',
  css: '[name].[contenthash:8].css',
  svg: '[name].[contenthash:8].svg',
  font: '[name].[contenthash:8][ext]',
  image: '[name].[contenthash:8][ext]',
  media: '[name].[contenthash:8][ext]',
};

Sets the filename of dist files.

After the production build, Rsbuild will add a hash in the middle of the filename by default. If you don't need to add it, you can set output.filenameHash to false to disable this behavior.

The following are the details of each filename:

  • js: The name of the JavaScript files.
  • css: The name of the CSS files.
  • svg: The name of the SVG images.
  • font: The name of the font files.
  • image: The name of non-SVG images.
  • media: The name of media assets, such as video.

Example

To set the name of the JavaScript file to [name]_script.js, use the following configuration:

export default {
  output: {
    filename: {
      js:
        process.env.NODE_ENV === 'production'
          ? '[name]_script.[contenthash:8].js'
          : '[name]_script.js',
    },
  },
};
Filename hash

Usually, we only set the filename hash in the production mode (i.e., when process.env.NODE_ENV === 'production').

If you set the filename hash in the development mode, it may cause HMR to fail (especially for CSS files). This is because every time the file content changes, the hash value changes, preventing bundler from reading the latest file content.

Filename of Async Modules

When you import a module via dynamic import, the module will be bundled into a single file, and its default naming rules are as follows:

  • In the development build, the filename will be generated based on the module path, such as dist/static/js/async/src_add_ts.js.
  • In the production build, it will be a random numeric id, such as dist/static/js/async/798.27e3083e.js. This is to avoid leaking the source code path in the production environment, and the number of characters is also less.
src/index.ts
const { add } = await import('./add.ts');

If you want to specify a fixed name for the async module, you can use the magic comments provided by the bundler to achieve this, using webpackChunkName to specify the module name:

src/index.ts
const { add } = await import(
  /* webpackChunkName: "my-chunk-name" */ './add.ts'
);

After specifying the module name as above, the generated file will be dist/static/js/async/my-chunk-name.js.

Using Function

You can pass a function to output.filename.js, allowing you to dynamically generate filenames based on file information:

export default {
  output: {
    filename: {
      js: (pathData, assetInfo) => {
        console.log(pathData); // You can check the contents of pathData here

        if (pathData.chunk?.name === 'index') {
          const isProd = process.env.NODE_ENV === 'production';
          return isProd ? '[name].[contenthash:8].js' : '[name].js';
        }

        return '/some-path/[name].js';
      },
    },
  },
};
TIP

Except for output.filename.js, other types of files currently do not support using functions.

Query Hash

If you need to generate hash values on the URL query of assets, you can refer to:

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

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

In this case, the filenames of JS and CSS will not include the hash, while the URLs in the HTML will contain a hash query.

<!doctype html>
<html>
  <head>
    <script defer src="/static/js/index.js?v=b8565050"></script>
    <link href="/static/css/index.css?v=02d157ca" rel="stylesheet" />
  </head>
</html>