实验#

启用并尝试一些实验性功能。

• 类型: object

experiments.asyncWebAssembly#

• 类型: boolean
• 默认值: false

根据 更新的规范 支持新的 WebAssembly，它使 WebAssembly 模块成为异步模块。

module.exports = {
  experiments: {
    asyncWebAssembly: true,
  },
};

当 experiments.futureDefaults 设置为 true 时，它默认情况下处于启用状态。

experiments.outputModule#

• 类型: boolean
• 默认值: true

启用后，Rspack 将尽可能输出 ECMAScript 模块语法。例如，import() 用于加载块，ESM 导出用于公开块数据，等等。

module.exports = {
  experiments: {
    outputModule: true,
  },
};

experiments.css#

• 类型: boolean
• 默认值: false

启用后，Rspack 将启用原生 CSS 支持，以及 CSS 相关的解析器和生成器选项。

• module.parser["css/auto"]
• module.parser.css
• module.parser["css/module"]
• module.generator["css/auto"]
• module.generator.css
• module.generator["css/module"]

基本示例

module.exports = {
  experiments: {
    css: true,
  },
};

experiments.futureDefaults#

使用下一个主要 Rspack 的默认值，并在任何存在问题的地方显示警告。

module.exports = {
  experiments: {
    futureDefaults: true,
  },
};

experiments.topLevelAwait#

启用对 顶层 await 的支持，顶层 await 只能在 ModuleType 为 javascript/esm 的模块中使用。

默认情况下启用，可以使用此配置禁用。

module.exports = {
  experiments: {
    topLevelAwait: false,
  },
};

experiments.lazyCompilation#

• 类型: boolean | LazyCompilationOptions
• 默认值: false

type LazyCompilationOptions =
  | boolean
  | {
      backend?: {
        /**
         * A custom client.
         */
        client?: string;
        /**
         * Specify where to listen to from the server.
         */
        listen?: number | ListenOptions;
        /**
         * Specify the protocol the client should use to connect to the server.
         */
        protocol?: 'http' | 'https';
      };
      /**
       * Enable lazy compilation for entries.
       */
      entries?: boolean;
      /**
       * Enable lazy compilation for dynamic imports.
       */
      imports?: boolean;
      /**
       * Specify which imported modules should be lazily compiled.
       */
      test?: RegExp | ((m: Module) => boolean);
    };

启用延迟编译，这可以极大地提高多页面应用程序 (MPA) 或大型单页面应用程序 (SPA) 的开发启动性能。例如，如果您有 20 个入口点，则只会构建访问的入口点。或者，如果项目中有很多 import() 语句，则只有在实际访问时才会构建 import() 指向的每个模块。

如果设置为 true，延迟编译将默认应用于入口模块和 import() 指向的模块。您可以通过配置对象决定它是否仅应用于入口，或者仅应用于 import()。entries 选项决定它是否应用于入口，而 import() 选项决定它是否应用于 import()。

const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  experiments: {
    // only enabled in dev mode
    lazyCompilation: isDev,
  },
};

此外，您还可以为延迟编译的模块配置一个 test 参数，以更精细地控制。test 参数可以是一个正则表达式，它只匹配应该延迟编译的那些模块。它也可以是一个函数，其中输入是类型 'Module'，并返回一个布尔值，指示它是否满足延迟编译逻辑的条件。

experiments.lazyCompilation.backend.listen#

• 类型： number | ListenOptions

type ListenOptions = {
  port?: number | undefined;
  host?: string | undefined;
  backlog?: number | undefined;
  path?: string | undefined;
  exclusive?: boolean | undefined;
  readableAll?: boolean | undefined;
  writableAll?: boolean | undefined;
  /**
   * @default false
   */
  ipv6Only?: boolean | undefined;
};

排除 HMR 客户端#

如果您不使用 Rspack 自身的开发服务器，而是使用您自己的服务器作为开发服务器，您通常需要在入口配置中添加另一个客户端模块来启用 HMR 等功能。最好通过配置 test 将这些客户端模块从延迟编译中排除。

如果不排除并且启用了入口的延迟编译，则在首次访问页面时不会编译此客户端，因此需要额外刷新才能使其生效。

例如

const rspack = require('@rspack/core');

const options = {
  experiments: {
    lazyCompilation: {
      test(module) {
        const isMyClient = module.nameForCondition().endsWith('dev-client.js');
        // make sure that dev-client.js won't be lazy compiled
        return !isMyClient;
      },
    },
  },
};
const compiler = rspack(options);

new compiler.webpack.EntryPlugin(compiler.context, 'dev-client.js', {
  // name: undefined means this is global entry
  name: undefined,
}).apply(compiler);

experiments.layers#

• 类型: boolean
• 默认值: false

控制是否启用层功能。层可以在模块图中从某个模块开始的子图中的所有模块添加标识符前缀，以将其与不同层中的模块区分开来。例如

index.js 模块的 layer 默认情况下为 null，其 identifier 为 ./index.js。如果我们为其设置 layer = 'client'，其 identifier 将变为 (client)/./index.js。此时，这两个不同层中的 index.js 模块将被视为不同的模块，因为它们的唯一 identifier 不同。因此，最终的输出将包含这两个模块的工件。

默认情况下，模块的层为 null，它将继承其父模块的层。您可以使用 entryOptions.layer 将层添加到入口模块，并且可以使用 module.rule[].layer 将层添加到匹配的模块。此外，您可以使用 module.rule[].issuerLayer 基于父模块的层进行匹配。

module.exports = {
  experiments: {
    layers: true,
  },
};

experiments.rspackFuture#

• 类型: object

• 默认值：有关详细信息，请参阅下面的选项

用于控制是否启用 Rspack 未来默认选项，请查看详细信息 此处。

experiments.rspackFuture.bundlerInfo#

• 类型:

  type BundlerInfo = {
    version?: string,
    bundler?: string,
    force?: ('version' | 'uniqueId')[] ｜ boolean;
  };

用于将当前使用的 Rspack 信息注入到生成的资源中

• version：用于指定 Rspack 版本，默认为 @rspack/core/package.json 中的 version 字段。
• bundler：用于指定打包工具的名称，默认为 rspack。
• force：是否强制注入 Rspack 信息，这将作为运行时模块添加到块中，默认为 true 以强制注入。可以使用数组来选择要强制注入的项目。

禁用默认注入#

可以通过将 force 设置为 false 来禁用默认注入。然后，只有在代码中检测到 __rspack_version__ 和 __rspack_unique_id__ 时才会进行注入

• __rspack_version__：注入版本信息。
• __rspack_unique_id__：注入打包工具的唯一 ID。

module.exports = {
  experiments: {
    rspackFuture: { bundlerInfo: { force: false } },
  },
};