#底层插件

这些插件是 Rspack 对外暴露的底层构件，主要用于实现目标预设、运行时模板、子编译器和上层插件。

底层插件分为以下类别：

• environment
• entry
• output
• loader
• module federation
• experiments

#environment

影响编译器环境和运行目标的插件。

#ElectronTargetPlugin

electron.ElectronTargetPlugin(context)

ElectronTargetPlugin 会将 Electron 内置模块保留为外部依赖，使其在运行时由 Electron 加载。传入 'main'、'preload' 或 'renderer'，可以额外外置对应进程中可用的模块。

externalsPresets.electron、externalsPresets.electronMain、externalsPresets.electronRenderer 和 externalsPresets.electronPreload 配置会在内部应用该插件。

对于常规 Electron 应用，推荐使用对应的 target：

export default {
  target: 'electron-main',
  entry: './src/main.js',
};

配置子编译器时，可以直接将插件应用到该编译器：

new compiler.rspack.electron.ElectronTargetPlugin('main').apply(childCompiler);

#NodeEnvironmentPlugin

node.NodeEnvironmentPlugin()

将 Node.js 风格的文件系统应用到编译器。

#NodeTargetPlugin

node.NodeTargetPlugin()

NodeTargetPlugin 会将 Node.js 内置模块和使用 node: scheme 的请求保留为外部依赖，使其由 Node.js 运行时加载，而不是被 Rspack 打进 bundle。externalsPresets.node 配置会在内部应用该插件。

对于常规 Node.js 应用，推荐使用 node target：

export default {
  target: 'node',
  entry: './src/index.js',
};

配置子编译器时，可以直接将插件应用到该编译器：

new compiler.rspack.node.NodeTargetPlugin().apply(childCompiler);

#entry

向 compilation 添加入口 chunk 的插件。

#DynamicEntryPlugin

DynamicEntryPlugin(context, entry)

与 EntryPlugin 类似，但接受一个函数作为 entry 参数。该函数会在每次触发 make 事件时调用，以动态决定入口点。

#EntryOptionPlugin

EntryOptionPlugin()

#output

影响模块、chunk 和运行时加载代码生成的插件。

#EnableChunkLoadingPlugin

javascript.EnableChunkLoadingPlugin(type)

EnableChunkLoadingPlugin 会启用指定 chunk loading 类型所需的运行时模块。Rspack 通常会根据 output.enabledChunkLoadingTypes 收集到的类型应用该插件。

支持的内置类型包括 'jsonp'、'import-scripts'、'require'、'async-node' 和 'import'。

当动态入口选择了 Rspack 在配置标准化阶段无法发现的类型时，可以直接应用该插件：

import { rspack } from '@rspack/core';

export default {
  entry: () => ({
    main: {
      import: './src/index.js',
      chunkLoading: 'jsonp',
    },
  }),
  output: {
    chunkLoading: false,
  },
  plugins: [new rspack.javascript.EnableChunkLoadingPlugin('jsonp')],
};

自定义 chunk loading 实现可以在安装相应运行时钩子后调用 EnableChunkLoadingPlugin.setEnabled(compiler, type)。该方法只注册类型，并不会实现 chunk loading。

#EnableLibraryPlugin

library.EnableLibraryPlugin(type)

EnableLibraryPlugin 会向编译器注册一种 library 输出类型。Rspack 通常会根据 output.enabledLibraryTypes 收集到的类型应用该插件。

下面的动态入口选择 'var' library 类型。由于 Rspack 无法在配置标准化阶段检查函数入口，因此需要显式启用该类型：

export const add = (a, b) => a + b;

import { rspack } from '@rspack/core';

export default {
  entry: () => ({
    main: {
      import: './src/index.js',
      library: {
        name: 'MathLibrary',
        type: 'var',
      },
    },
  }),
  plugins: [new rspack.library.EnableLibraryPlugin('var')],
};

常规 library 构建应优先使用 output.library，Rspack 会自动启用其中的 library 类型。

#EnableWasmLoadingPlugin

wasm.EnableWasmLoadingPlugin(type)

EnableWasmLoadingPlugin 会启用指定 WebAssembly 加载类型所需的运行时模块。Rspack 通常会根据 output.enabledWasmLoadingTypes 收集到的类型应用该插件。

支持的类型包括 'fetch'、'async-node' 和 'universal'。

下面的示例将 output.wasmLoading 设为 false 以关闭自动配置，然后直接应用 EnableWasmLoadingPlugin 安装 'fetch' 加载运行时：

import { add } from './add.wasm';

console.log(add(1, 2));

import { rspack } from '@rspack/core';

export default {
  target: 'web',
  entry: './src/index.js',
  experiments: {
    asyncWebAssembly: true,
  },
  output: {
    wasmLoading: false,
  },
  plugins: [new rspack.wasm.EnableWasmLoadingPlugin('fetch')],
};

常规构建应优先使用 output.wasmLoading，Rspack 会自动启用所选类型。

#EvalDevToolModulePlugin

EvalDevToolModulePlugin(options)

使用带有 // @sourceURL 注释的 eval 包裹每个模块，以装饰模块模板。

#FetchCompileAsyncWasmPlugin

web.FetchCompileAsyncWasmPlugin()

为异步获取和编译 WebAssembly 模块提供运行时代码，通常配合子编译器使用。

#JsonpTemplatePlugin

web.JsonpTemplatePlugin()

JsonpTemplatePlugin 用于配置子编译器的浏览器产物。它会将 output.chunkLoading 设置为 'jsonp'，应用 'array-push' chunk format，并启用 JSONP chunk loading 所需的运行时代码。

下面的浏览器入口会生成一个异步 chunk：

document.querySelector('button').addEventListener('click', async () => {
  const { message } = await import('./message.js');
  console.log(message);
});

export const message = 'Hello from the child compiler';

下面的配置会创建一个子编译器，并直接应用 JsonpTemplatePlugin：

export default {
  target: 'web',
  entry: {},
  plugins: [
    (compiler) => {
      compiler.hooks.make.tapAsync(
        'BrowserChildCompiler',
        (compilation, callback) => {
          const childCompiler = compilation.createChildCompiler(
            'browser-child',
            {
              filename: 'browser-child.js',
              chunkFilename: '[name].browser-child.js',
            },
            [
              new compiler.rspack.web.JsonpTemplatePlugin(),
              new compiler.rspack.EntryPlugin(
                compiler.context,
                './src/browser-child.js',
                { name: 'browser-child' },
              ),
            ],
          );

          childCompiler.runAsChild((error) => callback(error));
        },
      );
    },
  ],
};

JsonpTemplatePlugin 会让子编译器生成 array-push chunk，并在需要加载异步 chunk 时向页面添加 script。

对于常规 web 构建，推荐使用 target: 'web'。Rspack 会通过该 target 的默认配置选择 'array-push' chunk format 和 'jsonp' chunk loading。设置 output.chunkLoading: 'jsonp' 只会选择加载实现，并不会应用 JsonpTemplatePlugin 或选择 chunk format。

#NodeTemplatePlugin

node.NodeTemplatePlugin(options)

NodeTemplatePlugin 用于配置子编译器的 Node.js 产物。它会应用 'commonjs' chunk format，默认将 output.chunkLoading 设置为 'require'，并启用所需的 chunk loading 运行时代码。

#asyncChunkLoading

• 类型：boolean
• 默认值：false

当 asyncChunkLoading 为 true 时，该插件会使用 'async-node' chunk loading，而不是 'require'。

下面的 Node.js 入口会生成一个异步 chunk：

async function main() {
  const { run } = await import('./task.js');
  run();
}

main();

export function run() {
  console.log('Task completed');
}

下面的配置会创建一个子编译器，并直接应用 NodeTemplatePlugin：

export default {
  target: 'node',
  entry: {},
  plugins: [
    (compiler) => {
      compiler.hooks.make.tapAsync(
        'NodeChildCompiler',
        (compilation, callback) => {
          const childCompiler = compilation.createChildCompiler(
            'node-child',
            {
              filename: 'node-child.js',
              chunkFilename: '[name].node-child.js',
            },
            [
              new compiler.rspack.node.NodeTemplatePlugin(),
              new compiler.rspack.EntryPlugin(
                compiler.context,
                './src/node-child.js',
                { name: 'node-child' },
              ),
            ],
          );

          childCompiler.runAsChild((error) => callback(error));
        },
      );
    },
  ],
};

NodeTemplatePlugin 会让子编译器生成 CommonJS chunk，并通过 require 加载其中的异步 chunk。

对于常规 Node.js 构建，推荐使用 target: 'node'。Rspack 会通过该 target 的默认配置选择 'commonjs' chunk format 和 'require' chunk loading。设置 output.chunkLoading: 'require' 只会选择加载实现，并不会应用 NodeTemplatePlugin 或选择 chunk format。

#WebWorkerTemplatePlugin

webworker.WebWorkerTemplatePlugin()

WebWorkerTemplatePlugin 用于配置子编译器的 Web Worker 产物。它会将 output.chunkLoading 设置为 'import-scripts'，应用 'array-push' chunk format，并启用基于 importScripts 的 chunk loading 运行时代码。

下面的 Worker 入口会生成一个异步 chunk：

self.onmessage = async ({ data }) => {
  const { double } = await import('./math.js');
  self.postMessage(double(data));
};

export const double = (value) => value * 2;

下面的配置会创建一个子编译器，并直接应用 WebWorkerTemplatePlugin：

export default {
  target: 'webworker',
  entry: {},
  plugins: [
    (compiler) => {
      compiler.hooks.make.tapAsync(
        'WorkerChildCompiler',
        (compilation, callback) => {
          const childCompiler = compilation.createChildCompiler(
            'worker-child',
            {
              filename: 'worker-child.js',
              chunkFilename: '[name].worker-child.js',
            },
            [
              new compiler.rspack.webworker.WebWorkerTemplatePlugin(),
              new compiler.rspack.EntryPlugin(
                compiler.context,
                './src/worker-child.js',
                { name: 'worker-child' },
              ),
            ],
          );

          childCompiler.runAsChild((error) => callback(error));
        },
      );
    },
  ],
};

WebWorkerTemplatePlugin 会让子编译器生成 array-push chunk，并通过 importScripts 加载其中的异步 chunk。

对于常规 Web Worker 构建，推荐使用 target: 'webworker'。Rspack 会通过该 target 的默认配置选择 'array-push' chunk format 和 'import-scripts' chunk loading。设置 output.chunkLoading: 'import-scripts' 只会选择加载实现，并不会应用 WebWorkerTemplatePlugin 或选择 chunk format。

#loader

#LoaderOptionsPlugin

LoaderOptionsPlugin(options)

#LoaderTargetPlugin

LoaderTargetPlugin(target)

#module federation

ModuleFederationPlugin 使用的底层插件。

#ContainerPlugin

container.ContainerPlugin(options)

#ContainerReferencePlugin

container.ContainerReferencePlugin(options)

#ConsumeSharedPlugin

sharing.ConsumeSharedPlugin(options)

#ProvideSharedPlugin

sharing.ProvideSharedPlugin(options)

#SharePlugin

sharing.SharePlugin(options)

#TreeShakingSharedPlugin

sharing.TreeShakingSharedPlugin(options)

TreeShakingSharedPlugin 会为 Module Federation 共享依赖创建独立构建并优化导出。当至少一个 shared 依赖启用了 treeShaking 时，ModuleFederationPlugin 会自动应用该插件。

#选项

• mfConfig：用于配置共享依赖和产物的 ModuleFederationPluginOptions。
• secondary：是否在独立构建中执行第二次 tree shaking，默认值为 false。
• onBuildAssets：生成共享 fallback 产物后调用的回调函数。

直接应用该插件主要适用于部署平台在收集完整依赖信息后执行二次构建的场景：

import { sharing } from '@rspack/core';

export default {
  plugins: [
    new sharing.TreeShakingSharedPlugin({
      secondary: true,
      mfConfig: {
        name: 'app',
        shared: {
          'lodash-es': { treeShaking: { mode: 'server-calc' } },
        },
        library: { type: 'var', name: 'App' },
        manifest: true,
      },
    }),
  ],
};

该插件只会为启用了 treeShaking 且保留本地实现的共享依赖创建独立构建。启用 mfConfig.manifest 后，生成的 fallback 产物信息会写入 stats 和 manifest。

#experiments

#RemoveDuplicateModulesPlugin

experiments.RemoveDuplicateModulesPlugin()