feat: support for dynamic asset filenames (#4656)

Author: chenjiahan

e2e/cases/assets/filename-function/index.test.ts

@@ -32,4 +32,28 @@ test('should allow to custom filename by function', async () => {
       filename.includes('dist/static/css/async/some-path/foo.css'),
     ),
   ).toBeTruthy();
+
+  // Image
+  expect(
+    filenames.some((filename) =>
+      filename.includes('dist/static/image/my-icon.png'),
+    ),
+  ).toBeTruthy();
+  expect(
+    filenames.some((filename) =>
+      filename.includes('dist/static/image/some-path/image.png'),
+    ),
+  ).toBeTruthy();
+
+  // SVG
+  expect(
+    filenames.some((filename) =>
+      filename.includes('dist/static/svg/my-circle.svg'),
+    ),
+  ).toBeTruthy();
+  expect(
+    filenames.some((filename) =>
+      filename.includes('dist/static/svg/some-path/mobile.svg'),
+    ),
+  ).toBeTruthy();
 });

e2e/cases/assets/filename-function/rsbuild.config.ts

@@ -16,6 +16,18 @@ export default defineConfig({
         }
         return '/some-path/[name].css';
       },
+      image: (pathData) => {
+        if (pathData.filename?.includes('icon.png')) {
+          return 'my-icon.png';
+        }
+        return '/some-path/[name][ext]';
+      },
+      svg: (pathData) => {
+        if (pathData.filename?.includes('circle.svg')) {
+          return 'my-circle.svg';
+        }
+        return '/some-path/[name][ext]';
+      },
     },
   },
 });

e2e/cases/assets/filename-function/src/index.js

@@ -1,3 +1,9 @@
 import './index.css';
+import circle from '@assets/circle.svg?url';
+import icon from '@assets/icon.png?url';
+import image from '@assets/image.png?url';
+import mobile from '@assets/mobile.svg?url';
+
+console.log(icon, image, circle, mobile);
 
 import(/* webpackChunkName: "foo" */ './async');

packages/core/src/helpers/index.ts

@@ -226,7 +226,7 @@ export function getFilename(
   type: Exclude<keyof FilenameConfig, 'js' | 'css'>,
   isProd: boolean,
   isServer?: boolean,
-): string;
+): Rspack.AssetModuleFilename;
 export function getFilename(
   config: NormalizedConfig | NormalizedEnvironmentConfig,
   type: keyof FilenameConfig,

packages/core/src/plugins/asset.ts

@@ -1,5 +1,8 @@
 import path from 'node:path';
-import type { GeneratorOptionsByModuleType } from '@rspack/core';
+import type {
+  AssetModuleFilename,
+  GeneratorOptionsByModuleType,
+} from '@rspack/core';
 import { CHAIN_ID } from '../configChain';
 import {
   AUDIO_EXTENSIONS,
@@ -20,7 +23,7 @@ const chainStaticAssetRule = ({
   emit: boolean;
   rule: RspackChain.Rule;
   maxSize: number;
-  filename: string;
+  filename: AssetModuleFilename;
   assetType: string;
 }) => {
   const generatorOptions:
@@ -79,9 +82,17 @@ export const pluginAsset = (): RsbuildPlugin => ({
 
       const getMergedFilename = (
         assetType: 'svg' | 'font' | 'image' | 'media' | 'assets',
-      ) => {
+      ): AssetModuleFilename => {
         const distDir = config.output.distPath[assetType];
         const filename = getFilename(config, assetType, isProd);
+
+        if (typeof filename === 'function') {
+          return (...args) => {
+            const name = filename(...args);
+            return path.posix.join(distDir, name);
+          };
+        }
+
         return path.posix.join(distDir, filename);
       };
 

packages/core/src/types/config.ts

@@ -759,6 +759,11 @@ export type DistPathConfig = {
 };
 
 export type FilenameConfig = {
+  /**
+   * The name of HTML files.
+   * @default `[name].html`
+   */
+  html?: string;
   /**
    * The name of the JavaScript files.
    * @default
@@ -777,32 +782,27 @@ export type FilenameConfig = {
    * The name of the SVG images.
    * @default '[name].[contenthash:8].svg'
    */
-  svg?: string;
-  /**
-   * The name of HTML files.
-   * @default `[name].html`
-   */
-  html?: string;
+  svg?: Rspack.AssetModuleFilename;
   /**
    * The name of the font files.
    * @default '[name].[contenthash:8][ext]'
    */
-  font?: string;
+  font?: Rspack.AssetModuleFilename;
   /**
    * The name of non-SVG images.
    * @default '[name].[contenthash:8][ext]'
    */
-  image?: string;
+  image?: Rspack.AssetModuleFilename;
   /**
    * The name of media assets, such as video.
    * @default '[name].[contenthash:8][ext]'
    */
-  media?: string;
+  media?: Rspack.AssetModuleFilename;
   /**
    * the name of other assets, except for above (image, svg, font, html, wasm...)
    * @default '[name].[contenthash:8][ext]'
    */
-  assets?: string;
+  assets?: Rspack.AssetModuleFilename;
 };
 
 export type DataUriLimit = {

website/docs/en/config/output/filename.mdx

@@ -7,11 +7,11 @@ type FilenameConfig = {
   html?: string;
   js?: string | Function;
   css?: string | Function;
-  svg?: string;
-  font?: string;
-  image?: string;
-  media?: string;
-  assets?: string;
+  svg?: string | Function;
+  font?: string | Function;
+  image?: string | Function;
+  media?: string | Function;
+  assets?: string | Function;
 };
 ```
 
@@ -49,7 +49,7 @@ After the production build, Rsbuild will add a hash in the middle of the filenam
 
 The following are the details of each filename:
 
-- `html`: The name of the HTML file.
+- `html`: The name of the HTML files.
 - `js`: The name of the JavaScript files.
 - `css`: The name of the CSS files.
 - `svg`: The name of the SVG images.
@@ -137,42 +137,72 @@ After specifying the module name as above, the generated file will be `dist/stat
 
 ## Using function
 
-You can pass a function to `output.filename.js` or `output.filename.css`, allowing you to dynamically generate filenames based on file information.
+You can pass a function to dynamically set the filename based on the file information.
 
 The function receives two parameters:
 
 - `pathData`: An object containing file path information.
 - `assetInfo`: An optional object containing additional assets information.
 
+Dynamically set the filename for JavaScript files:
+
 ```ts title="rsbuild.config.ts"
+const isProd = process.env.NODE_ENV === 'production';
+
 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';
       },
+    },
+  },
+};
+```
+
+Dynamically set the filename for CSS files:
+
+```ts title="rsbuild.config.ts"
+const isProd = process.env.NODE_ENV === 'production';
+
+export default {
+  output: {
+    filename: {
       css: (pathData, assetInfo) => {
         if (pathData.chunk?.name === 'index') {
-          const isProd = process.env.NODE_ENV === 'production';
           return isProd ? '[name].[contenthash:8].css' : '[name].css';
         }
-
         return '/some-path/[name].css';
       },
     },
   },
 };
 ```
 
+Dynamically set the filename for image files:
+
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    filename: {
+      image: (pathData) => {
+        if (pathData.filename?.includes('foo')) {
+          return '/foo/[name][ext]';
+        }
+        return '/bar/[name][ext]';
+      },
+    },
+  },
+};
+```
+
 :::tip
-Except for `output.filename.js` and `output.filename.css`, other types of files currently do not support using functions.
+`output.filename.html` does not support using functions yet.
 :::
 
 ## Query hash

website/docs/zh/config/output/filename.mdx

@@ -7,11 +7,11 @@ type FilenameConfig = {
   html?: string;
   js?: string | Function;
   css?: string | Function;
-  svg?: string;
-  font?: string;
-  image?: string;
-  media?: string;
-  assets?: string;
+  svg?: string | Function;
+  font?: string | Function;
+  image?: string | Function;
+  media?: string | Function;
+  assets?: string | Function;
 };
 ```
 
@@ -137,42 +137,72 @@ const { add } = await import(
 
 ## 使用函数
 
-`output.filename.js` 和 `output.filename.css` 可以传入一个函数，这允许你根据文件信息动态生成文件名。
+你可以传入一个函数来根据文件信息动态设置文件名。
 
-函数接收两个参数：
+这个函数接收两个参数：
 
 - `pathData`：一个对象，包含文件路径信息。
 - `assetInfo`：一个可选的对象，包含额外的资源信息。
 
+为 JavaScript 文件动态设置文件名：
+
 ```ts title="rsbuild.config.ts"
+const isProd = process.env.NODE_ENV === 'production';
+
 export default {
   output: {
     filename: {
       js: (pathData, assetInfo) => {
         console.log(pathData); // 你可以在这里查看 pathData 的内容
 
         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';
       },
+    },
+  },
+};
+```
+
+为 CSS 文件动态设置文件名：
+
+```ts title="rsbuild.config.ts"
+const isProd = process.env.NODE_ENV === 'production';
+
+export default {
+  output: {
+    filename: {
       css: (pathData, assetInfo) => {
         if (pathData.chunk?.name === 'index') {
-          const isProd = process.env.NODE_ENV === 'production';
           return isProd ? '[name].[contenthash:8].css' : '[name].css';
         }
-
         return '/some-path/[name].css';
       },
     },
   },
 };
 ```
 
+为图片文件动态设置文件名：
+
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    filename: {
+      image: (pathData) => {
+        if (pathData.filename?.includes('foo')) {
+          return '/foo/[name][ext]';
+        }
+        return '/bar/[name][ext]';
+      },
+    },
+  },
+};
+```
+
 :::tip
-除了 `output.filename.js` 和 `output.filename.css` 以外，其他类型的文件目前暂不支持使用函数。
+`output.filename.html` 暂不支持使用函数。
 :::
 
 ## Query hash