feat: add new output.emitAssets config (#2134)

Author: chenjiahan

.changeset/fair-singers-chew.md

@@ -0,0 +1,5 @@
+---
+'@rsbuild/core': patch
+---
+
+release: 0.6.4

e2e/cases/emit-assets/index.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from '@playwright/test';
+import { build } from '@e2e/helper';
+
+test('should allow to disable emit assets for node target', async () => {
+  const rsbuild = await build({
+    cwd: __dirname,
+  });
+
+  const files = await rsbuild.unwrapOutputJSON();
+  const filenames = Object.keys(files);
+
+  expect(
+    filenames.some((filename) =>
+      filename.includes('dist/static/image/icon.png'),
+    ),
+  ).toBeTruthy();
+
+  expect(
+    filenames.some((filename) =>
+      filename.includes('dist/server/static/image/icon.png'),
+    ),
+  ).toBeFalsy();
+});

e2e/cases/emit-assets/rsbuild.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  output: {
+    filenameHash: false,
+    targets: ['web', 'node'],
+    emitAssets: ({ target }) => target !== 'node',
+  },
+});

e2e/cases/emit-assets/src/index.js

@@ -0,0 +1,3 @@
+import small from '../../../assets/icon.png?url';
+
+console.log(small);

packages/core/src/config.ts

@@ -150,6 +150,7 @@ const getDefaultOutputConfig = (): NormalizedOutputConfig => ({
     auto: true,
     exportLocalsConvention: 'camelCase',
   },
+  emitAssets: () => true,
 });
 
 const createDefaultConfig = (): RsbuildConfig => ({

packages/core/src/mergeConfig.ts

@@ -11,6 +11,7 @@ const OVERRIDE_PATH = [
   'output.inlineStyles',
   'output.cssModules.auto',
   'output.targets',
+  'output.emitAssets',
   'server.printUrls',
   'dev.startUrl',
   'provider',

packages/core/src/plugins/asset.ts

@@ -9,26 +9,37 @@ import {
   type BundlerChainRule,
 } from '@rsbuild/shared';
 import type { RsbuildPlugin } from '../types';
+import type { GeneratorOptionsByModuleType } from '@rspack/core';
 
 const chainStaticAssetRule = ({
+  emit,
   rule,
   maxSize,
   filename,
   assetType,
 }: {
+  emit: boolean;
   rule: BundlerChainRule;
   maxSize: number;
   filename: string;
   assetType: string;
 }) => {
+  const generatorOptions:
+    | GeneratorOptionsByModuleType['asset']
+    | GeneratorOptionsByModuleType['asset/resource'] = {
+    filename,
+  };
+
+  if (emit === false) {
+    generatorOptions.emit = false;
+  }
+
   // force to url: "foo.png?url" or "foo.png?__inline=false"
   rule
     .oneOf(`${assetType}-asset-url`)
     .type('asset/resource')
     .resourceQuery(/(__inline=false|url)/)
-    .set('generator', {
-      filename,
-    });
+    .set('generator', generatorOptions);
 
   // force to inline: "foo.png?inline"
   rule
@@ -45,9 +56,7 @@ const chainStaticAssetRule = ({
         maxSize,
       },
     })
-    .set('generator', {
-      filename,
-    });
+    .set('generator', generatorOptions);
 };
 
 export function getRegExpForExts(exts: string[]): RegExp {
@@ -66,12 +75,13 @@ export const pluginAsset = (): RsbuildPlugin => ({
   name: 'rsbuild:asset',
 
   setup(api) {
-    api.modifyBundlerChain((chain, { isProd }) => {
+    api.modifyBundlerChain((chain, { isProd, target }) => {
       const config = api.getNormalizedConfig();
 
       const createAssetRule = (
         assetType: 'image' | 'media' | 'font' | 'svg',
         exts: string[],
+        emit: boolean,
       ) => {
         const regExp = getRegExpForExts(exts);
         const distDir = getDistPath(config, assetType);
@@ -84,17 +94,24 @@ export const pluginAsset = (): RsbuildPlugin => ({
         const rule = chain.module.rule(assetType).test(regExp);
 
         chainStaticAssetRule({
+          emit,
           rule,
           maxSize,
           filename: path.posix.join(distDir, filename),
           assetType,
         });
       };
 
-      createAssetRule('image', IMAGE_EXTENSIONS);
-      createAssetRule('svg', ['svg']);
-      createAssetRule('media', [...VIDEO_EXTENSIONS, ...AUDIO_EXTENSIONS]);
-      createAssetRule('font', FONT_EXTENSIONS);
+      const emit = config.output.emitAssets({ target });
+
+      createAssetRule('image', IMAGE_EXTENSIONS, emit);
+      createAssetRule('svg', ['svg'], emit);
+      createAssetRule(
+        'media',
+        [...VIDEO_EXTENSIONS, ...AUDIO_EXTENSIONS],
+        emit,
+      );
+      createAssetRule('font', FONT_EXTENSIONS, emit);
     });
   },
 });

packages/document/docs/en/config/output/emit-assets.mdx

@@ -0,0 +1,26 @@
+# output.emitAssets
+
+- **Type:**
+
+```ts
+type EmitAssets = (params: { target: RsbuildTarget }) => boolean;
+```
+
+- **Default:** `() => true`
+
+Control whether to emit static assets such as images, fonts, audio, video, etc.
+
+In scenarios such as SSR, you may not need to emit duplicate static assets. Therefore, you can return `false` in `emitAssets` to emitting assets.
+
+## Example
+
+For example, the following example will emit static assets when building web bundles, and avoid emitting when building node bundles.
+
+```js
+export default {
+  output: {
+    targets: ['web', 'node'],
+    emitAssets: ({ target }) => target !== 'node',
+  },
+};
+```

packages/document/docs/en/guide/basic/static-assets.md

@@ -1,6 +1,6 @@
 # Import Static Assets
 
-Rsbuild supports import static assets, including images, fonts, and medias.
+Rsbuild supports import static assets, including images, fonts, audio and video.
 
 :::tip What is Static Assets
 Static assets are files that are part of a web application and do not change, even when the application is being used. Examples of static assets include images, fonts, medias, stylesheets, and JavaScript files. These assets are typically stored on a web server or CDN, and delivered to the user's web browser when the Web application is accessed. Because they do not change, static assets can be cached by the browser, which helps to improve the performance of the Web application.
@@ -10,7 +10,7 @@ Static assets are files that are part of a web application and do not change, ev
 
 The following are the formats supported by Rsbuild by default:
 
-- **image**: png, jpg, jpeg, gif, svg, bmp, webp, ico, apng, avif, tif, tiff, jfif, pjpeg, pjp.
+- **images**: png, jpg, jpeg, gif, svg, bmp, webp, ico, apng, avif, tif, tiff, jfif, pjpeg, pjp.
 - **fonts**: woff, woff2, eot, ttf, otf, ttc.
 - **audio**: mp3, wav, flac, aac, m4a, opus.
 - **video**: mp4, webm, ogg, mov.

packages/document/docs/zh/config/output/emit-assets.mdx

@@ -0,0 +1,26 @@
+# output.emitAssets
+
+- **类型：**
+
+```ts
+type EmitAssets = (params: { target: RsbuildTarget }) => boolean;
+```
+
+- **默认值：** `() => true`
+
+用于控制是否输出图片、字体、音频、视频等静态资源。
+
+在 SSR 等场景下，你可能不需要输出重复的静态资源，因此你可以在 `emitAssets` 返回 `false` 来避免资源输出。
+
+## 示例
+
+比如，以下例子会在构建 web 产物时输出静态资源，而在构建 node 产物时避免输出。
+
+```js
+export default {
+  output: {
+    targets: ['web', 'node'],
+    emitAssets: ({ target }) => target !== 'node',
+  },
+};
+```