Module

模块:该选项用于决定如何处理一个项目中不同类型的模块。

  • 类型: Object
  • 默认值: {}

module.rules

  • 类型: Rule[]
  • 默认值: []

一个规则数组,当模块被创建时与该模块的请求相匹配。这些规则可以修改模块的创建行为。它们可以对模块应用 Loader 等。

Rule

  • 类型: Rule
  • 默认值: {}

Rule 定义了一个模块的匹配条件以及处理这些模块的行为。

Rule 处理行为

定义了对应匹配的模块的处理行为,例如:

  • 将 Loader 的列表应用到这些模块上(Rule.use
  • 定义模块的类型(Rule.type
  • 定义模块的 resolve 配置(Rule.resolve

Condition

  • 类型: string | RegExp | Condition[] | LogicalConditions

定义了一个模块的匹配条件,常见的匹配有和 resourceresourceQuery 的匹配,以及 includeexclude 的匹配等。

例如: 当 app.js 导入 ./image.png?inline#foo

  • resource/path/to/image.png,会与 Rule.resource 这个 Condition 进行匹配
  • resourceQuery?inline,会与 Rule.resourceQuery 这个 Condition 进行匹配
  • resourceFragment#foo,会与 Rule.resourceFragment 这个 Condition 进行匹配

Condition 代表了匹配一个给定输入的形式,它支持的类型为:

  • String:给定一个输入,当输入的字符串满足 startsWith 时,则匹配成功。注:你可以认为是 input.startsWith(condition)
  • RegExp:给定一个输入,当输入的字符串满足正则表达式时,则匹配成功。注:你可以认为是 condition.test(input)
  • Condition[]:一系列条件,当有一个条件匹配上时,则匹配成功。
  • LogicalConditions:所有属性都匹配上时,则匹配成功。
    • { and: Condition[] }:所有条件都匹配,则匹配成功。
    • { or: Condition[] }:其中一个条件匹配,则匹配成功。
    • { not: Condition }:所有条件都不匹配时,则匹配成功。
  • (value: string) => boolean:当输入的字符串经函数调用后返回 true 是,则匹配成功。

Nested Rule

嵌套 Rule 可以通过 Rule.rulesRule.oneOf 定义,这些嵌套 Rule 只有在其上层 Rule 匹配成功时才会进行匹配,它们可以包含自己的 Rule 条件

嵌套 Rule 的匹配顺序:

  1. 其上层 Rule
  2. Rule.rules
  3. Rule.oneOf

Rule.exclude

排除所有符合这个条件的模块,会和资源的绝对路径(不包含 query 和 fragment)进行匹配。该选项不能和 Rule.resource 同时存在。

Rule.include

匹配所有符合这个条件的模块,会和资源的绝对路径(不包含 query 和 fragment)进行匹配。该选项不能和 Rule.resource 同时存在。

Rule.resource

匹配所有符合这个资源的模块,会和 Resource(不包含 query 和 fragment 的绝对路径)进行匹配。该选项不能和 Rule.test 同时存在。

Rule.resourceQuery

匹配所有符合这个资源的模块,会和 Resource 的 query 进行匹配。注:包含 ?,当 Rule.resourceQuery?raw 时,会和 xxx?raw 的资源请求进行匹配。

Rule.resourceFragment

匹配所有符合这个资源的模块,会和 Resource 的 fragment 进行匹配。注:包含 #,当 Rule.resourceFragment#abc 时,会和 xxx#abc 的资源请求进行匹配。

Rule.test

匹配所有符合这个资源的模块,会和 Resource(不包含 query 和 fragment 的绝对路径)进行匹配。该选项不能和 Rule.resource 同时存在。

Rule.issuer

匹配所有符合这个资源的模块,会和引入当前模块的模块的 Resource(不包含 query 和 fragment 的绝对路径)进行匹配。

Rule.dependency

匹配所有符合这个资源的模块,会和引入当前模块的依赖的类别(category)进行匹配,比如对于 importimport() 来说是 esm,对于 require() 来说是 cjs,对于 new URL()url() 来说是 url

Rule.scheme

匹配所有符合这个资源的模块,会和 Resource 的 scheme 进行匹配。

比如,你可以通过以下配置将内联的 data uri 资源当作单独的资源处理:

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        scheme: 'data',
        type: 'asset/resource',
      },
    ],
  },
};

Rule.mimetype

匹配所有符合这个资源的模块,会和 Resource 的 mimetype 进行匹配。

Rule.descriptionData

  • 类型: { [k: string]: Condition }
  • 默认值: undefined

匹配所有符合这个资源的模块,会和 Resource 的 package.json 中的字段进行匹配。

Rule.loaders

WARNING

这个选项已经被废弃,请使用 Rule.use 代替。

Rule.loader

Rule.loaderRule.use: [ { loader } ] 的简略写法。 详情见 Rule.use.

Rule.options

Rule.optionsRule.use: [ { options } ] 的简略写法。 详情见 Rule.use.

Rule.parser

  • 类型: Object
  • 默认值: {}

模块的 parser 配置。

Rule.parser.dataUrlCondition

  • 类型: object = { maxSize: number = 8096 }
  • 默认值: {}

如果当前模块的小于等于 maxSize,那么模块将被 Base64 编码,否则模块将会以文件形式被输出。该选项仅能做用于 Asset Module 的场景。

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.png$/,
        parser: {
          dataUrlCondition: {
            // 小于等于 4kb,且以 `.png` 结尾的模块将被 Base64 编码
            maxSize: 4 * 1024,
          },
        },
      },
    ],
  },
};

Rule.generator

  • 类型: Object
  • 默认值: {}

模块的生成器选项,例如:对于 Asset Module 可以指定输出文件名。

Rule.generator.filename

覆盖 output.assetModuleFilename,仅对模块类型为 'asset''asset/resource' 的模块生效。

rspack.config.js
module.exports = {
  //...
  output: {
    assetModuleFilename: 'images/[hash][ext]',
  },
  module: {
    rules: [
      {
        test: /\.png/,
        type: 'asset/resource',
      },
      {
        test: /\.html/,
        type: 'asset/resource',
        generator: {
          filename: 'static/[hash][ext]',
        },
      },
    ],
  },
};

Rule.generator.publicPath

  • 类型: string
  • 默认值: undefined

覆盖 output.publicPath,仅对模块类型为 'asset''asset/resource' 的模块生效。

rspack.config.js
module.exports = {
  //...
  output: {
    publicPath: 'https://example.com/',
  },
  module: {
    rules: [
      {
        test: /\.png/,
        type: 'asset/resource',
        generator: {
          publicPath: 'https://cdn.example.com/',
        },
      },
    ],
  },
};

Rule.generator.dataUrl

  • 类型: Object
  • 默认值: {}

仅对模块类型为 'asset/inline' 的模块生效。

rspack.config.js
module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.png/,
        type: 'asset/inline',
        generator: {
          dataUrl: {
            encoding: 'base64',
            mimetype: 'mimetype/png',
          },
        },
      },
    ],
  },
};

Rule.generator.dataUrl.encoding

  • 类型: false | 'base64'
  • 默认值: 'base64'

设置为 base64 时,模块将使用 base64 算法进行编码。将编码设置为 false 将禁用编码。仅对模块类型为 'asset/inline' 的模块生效。

Rule.generator.dataUrl.mimetype

  • 类型: string
  • 默认值: require('mime-types').lookup(ext)

dataUrl 的 MIME 类型,默认从模块资源扩展名解析。仅对模块类型为 'asset/inline' 的模块生效。

Rule.sideEffects

  • 类型: boolean

标记模块是否存在副作用。

Rule.type

  • 类型: 'javascript/auto' | 'typescript' | 'css' | 'css/module' | 'css/auto' | 'json' | 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline' | 'tsx' | 'jsx'

用于标记匹配的模块的类型,这会影响 Rspack 内置对于该模块的处理方式。例如:当模块被标记为 'typescript' 则会使用 TS parser/generator 对模块进行处理。

  • 'javascript/auto':JavaScript 模块,支持的模块系统:CommonJS、ESM,暂没有对 AMD 模块支持的计划。
  • 'javascript/esm':JavaScript 模块,当作严格 ES Module 处理。
  • 'javascript/dynamic':JavaScript 模块,当作 Script 处理。
  • 'jsx': 支持 jsx 的 JavaScript 模块(🚧 已废弃,详见 experiments.rspackFuture.disableTransformByDefault)。
  • 'typescript':TypeScript 模块(🚧 已废弃)。
  • 'tsx': 支持 tsx 的 TypeScript 模块(🚧 已废弃)。
  • 'css':CSS 模块。
  • 'css/module':CSS Modules 模块。
  • 'css/auto':基于文件名判断,若匹配/\.module(s)?\.[^.]+$/则为 CSS Modules 模块,否则为 CSS 模块。
  • 'json':JSON data 模块。
  • 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline':参考资源模块

Rule.use

  • 类型:
export type RuleSetUse =
  | RuleSetUseItem[]
  | RuleSetUseItem
  | ((ctx: RawFuncUseCtx) => RuleSetUseItem[]);
export type RuleSetUseItem =
  | { loader: string; options: Record<string, any> }
  | string;
export interface RawFuncUseCtx {
  resource?: string;
  realResource?: string;
  resourceQuery?: string;
  issuer?: string;
}

用于传递 Loader 包名与其选项的数组。string[] 如: use: ['svgr-loader']use: [ { loader: 'svgr-loader' } ] 的简写。Loader 会按照从右到左的顺序执行。

rspack.config.js
module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        use: [
          'svgr-loader',
          {
            loader: 'svgo-loader',
            options: {
              configFile: false,
            },
          },
        ],
      },
    ],
  },
};

也可以使用一个函数:

rspack.config.js
module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.svg$/,
        type: 'asset',
        use: (info) => ({
          loader: 'svgo-loader',
          options: {
            plugins: [
              {
                cleanupIDs: { prefix: basename(info.resource) },
              },
            ],
          },
        }),
      },
    ],
  },
};

Rule.resolve

根据匹配的模块设置具体的模块 resolve 选项

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        resolve: {
          preferRelative: true,
        },
      },
    ],
  },
};

Rule.rules

  • 类型: Rule[]
  • 默认值: undefined

嵌套 Rule 的一种,当其上层 Rule 匹配成功后会使用这些 Rule 进行匹配

Rule.oneOf

  • 类型: Rule[]
  • 默认值: undefined

嵌套 Rule 的一种,当其上层 Rule 匹配成功后会使用这些 Rule 进行匹配,并且只使用匹配成功的第一个 Rule

module.parser

  • 类型: Object
  • 默认值: {}

使用 module.parser 在一个地方配置所有解析器选项。

rspack.config.js
module.exports = {
  module: {
    parser: {
      asset: {
        // asset 模块的解析器选项
        dataUrlCondition: {
          maxSize: 8000,
        },
      },
    },
  },
};

module.parser.javascript

JavaScript parser 的配置项。

rspack.config.js
module.exports = {
  module: {
    parser: {
      javascript: {
        dynamicImportMode: 'lazy',
        url: true,
      },
    },
  },
};

module.parser.javascript.dynamicImportMode

指定动态导入的全局模式。

  • 类型: 'lazy' | 'eager'
  • 默认值: 'lazy'

module.parser.javascript.dynamicImportPrefetch

指定动态导入的全局 prefetch。

  • Type: boolean | number
  • Default: false

module.parser.javascript.dynamicImportPreload

指定动态导入的全局 preload。

  • Type: boolean | number
  • Default: false

module.parser.javascript.url

启用 new URL() 语法解析。

  • 类型: true | false | 'relative'
  • 默认值: true

当使用 'relative' 时,webpack 将为 new URL() 语法生成相对的 URL,即结果 URL 中不包含根 URL

<!-- 使用 'relative' -->
<img src="icon.svg" />

<!-- 不使用 'relative' -->
<img src="file:///path/to/project/dist/icon.svg" />

module.generator

  • 类型: Object
  • 默认值: {}

使用 module.generator 在一个地方配置所有生成器选项。

rspack.config.js
module.exports = {
  module: {
    generator: {
      asset: {
        // asset 模块的生成器选项
        publicPath: 'https://cdn.example.com/',
      },
      'asset/inline': {
        // asset/inline 模块的生成器选项
        dataUrl: {
          encoding: false,
        },
      },
      'asset/resource': {
        // asset/resource 模块的生成器选项
        filename: '[name]-[contenthash][ext]',
      },
    },
  },
};