diff --git a/packages/rspack/etc/api.md b/packages/rspack/etc/api.md index e74f894e3e0..d418016175c 100644 --- a/packages/rspack/etc/api.md +++ b/packages/rspack/etc/api.md @@ -5494,12 +5494,29 @@ const node_2: z.ZodUnion<[z.ZodLiteral, z.ZodObject<{ // @public (undocumented) interface Node_3 { + // (undocumented) + NodeEnvironmentPlugin: typeof NodeEnvironmentPlugin; // (undocumented) NodeTargetPlugin: typeof NodeTargetPlugin; // (undocumented) NodeTemplatePlugin: typeof NodeTemplatePlugin; } +// @public (undocumented) +class NodeEnvironmentPlugin { + constructor(options: NodeEnvironmentPluginOptions); + // (undocumented) + apply(compiler: Compiler): void; + // (undocumented) + options: NodeEnvironmentPluginOptions; +} + +// @public (undocumented) +interface NodeEnvironmentPluginOptions { + // (undocumented) + infrastructureLogging: InfrastructureLogging; +} + // @public (undocumented) interface NodeNextConfig extends BaseModuleConfig { // (undocumented) diff --git a/packages/rspack/scripts/check-documentation-coverage.mjs b/packages/rspack/scripts/check-documentation-coverage.mjs index 9b3eb3b211f..cba965a55de 100644 --- a/packages/rspack/scripts/check-documentation-coverage.mjs +++ b/packages/rspack/scripts/check-documentation-coverage.mjs @@ -1,11 +1,7 @@ -import { - ApiModel, - ApiItemKind, - ApiVariable -} from "@microsoft/api-extractor-model"; +import { ApiModel, ApiItemKind } from "@microsoft/api-extractor-model"; import { fileURLToPath } from "url"; -import { dirname, resolve, extname, basename } from "path"; -import { readdirSync } from "fs"; +import { dirname, resolve, extname, basename, join } from "path"; +import { readdirSync, readFileSync } from "fs"; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); @@ -13,6 +9,7 @@ const __dirname = dirname(__filename); const PLUGIN_REGEX = /^[A-Z][a-zA-Z]+Plugin$/; const PLUGIN_API_JSON = resolve(__dirname, "../temp/core.api.json"); const PLUGIN_DOCS_DIR = resolve(__dirname, "../../../website/docs/en/plugins"); +const INTERNAL_PLUGINS_DOC = join(PLUGIN_DOCS_DIR, "webpack/internal-plugins.mdx"); function getImplementedPlugins() { const apiModel = new ApiModel(); @@ -44,6 +41,16 @@ function toCamelCase(s) { .join(""); } +function extractMarkdownHeadings(markdown) { + const headingRegex = /^(#{1,6})\s+(.+)$/gm; + const headings = []; + let match; + while ((match = headingRegex.exec(markdown)) !== null) { + headings.push(match[2].trim()); + } + return headings; +} + function getDocumentedPlugins() { const documentedPlugins = new Set(); @@ -66,6 +73,14 @@ function getDocumentedPlugins() { } visitDir(PLUGIN_DOCS_DIR); + const internalPluginsDoc = readFileSync(INTERNAL_PLUGINS_DOC, 'utf-8'); + const headings = extractMarkdownHeadings(internalPluginsDoc); + for (const heading of headings) { + if (PLUGIN_REGEX.test(heading)) { + documentedPlugins.add(heading); + } + } + return documentedPlugins; } @@ -96,8 +111,6 @@ if (unimplementedPlugins.length) { ); } -// TODO: remove the comments below once all plugins have been documented -// if (undocumentedPlugins.length || unimplementedPlugins.length) { -if (unimplementedPlugins.length) { +if (undocumentedPlugins.length || unimplementedPlugins.length) { process.exit(1); } diff --git a/packages/rspack/src/exports.ts b/packages/rspack/src/exports.ts index 1701cb81f2b..1ed69d78c8d 100644 --- a/packages/rspack/src/exports.ts +++ b/packages/rspack/src/exports.ts @@ -122,11 +122,17 @@ export { NormalModuleReplacementPlugin } from "./lib/NormalModuleReplacementPlug import NodeTemplatePlugin from "./node/NodeTemplatePlugin"; import { NodeTargetPlugin } from "./builtin-plugin"; +import NodeEnvironmentPlugin from "./node/NodeEnvironmentPlugin"; interface Node { NodeTargetPlugin: typeof NodeTargetPlugin; NodeTemplatePlugin: typeof NodeTemplatePlugin; + NodeEnvironmentPlugin: typeof NodeEnvironmentPlugin; } -export const node: Node = { NodeTargetPlugin, NodeTemplatePlugin }; +export const node: Node = { + NodeTargetPlugin, + NodeTemplatePlugin, + NodeEnvironmentPlugin +}; import { ElectronTargetPlugin } from "./builtin-plugin"; interface Electron { diff --git a/website/docs/en/plugins/webpack/_meta.json b/website/docs/en/plugins/webpack/_meta.json index 1167697d5db..667156e72a4 100644 --- a/website/docs/en/plugins/webpack/_meta.json +++ b/website/docs/en/plugins/webpack/_meta.json @@ -1,6 +1,5 @@ [ "index", - "entry-plugin", "define-plugin", "provide-plugin", "banner-plugin", @@ -8,6 +7,7 @@ "ignore-plugin", "progress-plugin", "externals-plugin", + "eval-source-map-dev-tool-plugin", "source-map-dev-tool-plugin", "split-chunks-plugin", "node-target-plugin", @@ -15,10 +15,10 @@ "enable-chunk-loading-plugin", "enable-library-plugin", "enable-wasm-loading-plugin", - "electron-target-plugin", "module-federation-plugin", "module-federation-plugin-v1", "environment-plugin", "limit-chunk-count-plugin", - "normal-module-replacement-plugin" + "normal-module-replacement-plugin", + "internal-plugins" ] diff --git a/website/docs/en/plugins/webpack/eval-source-map-dev-tool-plugin.mdx b/website/docs/en/plugins/webpack/eval-source-map-dev-tool-plugin.mdx new file mode 100644 index 00000000000..9f0c946290e --- /dev/null +++ b/website/docs/en/plugins/webpack/eval-source-map-dev-tool-plugin.mdx @@ -0,0 +1,55 @@ +import WebpackLicense from '@components/webpack-license'; + + + +# EvalSourceMapDevToolPlugin + +This plugin enables more fine grained control of source map generation. It is also enabled automatically by certain settings of the [`devtool`](/config/devtool) configuration option. + +```js +new webpack.EvalSourceMapDevToolPlugin(options); +``` + +## Options + +### append + +- **Type:** `string | function` + +Appends the given value to the original asset. Usually the `#sourceMappingURL` comment. `[url]` is replaced with a URL to the source map file. `false` disables the appending. + +### module + +- **Type:** `boolean` + +Indicates whether loaders should generate source maps (defaults to `true`). + +### columns + +- **Type:** `boolean` + +Indicates whether column mappings should be used (defaults to `true`). + +## Examples + +### Basic Use Case + +You can use the following code to replace the configuration option `devtool: eval-source-map` with an equivalent custom plugin configuration: + +```js +module.exports = { + // ... + devtool: false, + plugins: [new rspack.EvalSourceMapDevToolPlugin({})], +}; +``` + +### Exclude Vendor Maps + +The following code would exclude source maps for any modules in the `vendor.js` bundle: + +```js +new rspack.EvalSourceMapDevToolPlugin({ + exclude: ['vendor.js'], +}); +``` diff --git a/website/docs/en/plugins/webpack/internal-plugins.mdx b/website/docs/en/plugins/webpack/internal-plugins.mdx new file mode 100644 index 00000000000..d5d96645abc --- /dev/null +++ b/website/docs/en/plugins/webpack/internal-plugins.mdx @@ -0,0 +1,175 @@ +import { ApiMeta } from '@components/ApiMeta.tsx'; +import WebpackLicense from '@components/webpack-license'; + + + +# Internal plugins + +This is a list of plugins used internally by Rspack, aligned with the plugins used internally by webpack. + +:::warning +You should only concern yourself with these plugins if you are building your own compiler based on Rspack, or for internal inspection. +::: + +Categories of internal plugins: + +- [environment](#environment) +- [compiler](#compiler) +- [entry](#entry) +- [output](#output) +- [source](#source) +- [optimize](#optimize) +- [loader](#loader) +- [module federation](#module-federation) + +## environment + +Plugins affecting the environment of the compiler. + +### ElectronTargetPlugin + +`electron.ElectronTargetPlugin(context)` + +Customizes the handling of external dependencies for different contexts (such as main process, preload scripts, and renderer process) in Electron applications. + +[`externalsPresets.electron`](/config/externals#electron), [`externalsPresets.electronMain`](/config/externals#electronmain), [`externalsPresets.electronRenderer`](/config/externals#electronrenderer), and [`externalsPresets.electronPreload`](/config/externals#electronpreload) all rely on this plugin. + +### NodeEnvironmentPlugin + +`node.NodeEnvironmentPlugin()` + +Applies Node.js style filesystem to the compiler. + +## compiler + +Plugins affecting the compiler. + +### ProgressPlugin + +`ProgressPlugin(handler)` + +Hook into the compiler to extract progress information. The `handler` must have the signature `function(percentage, message)`. Percentage is called with a value between 0 and 1, where 0 indicates the start and 1 the end. + +## entry + +Plugins, which add entry chunks to the compilation. + +### EntryPlugin + +`EntryPlugin(context, entry, options)` + +Adds an entry chunk on compilation. The chunk is named `options.name` and contains only one module (plus dependencies). The module is resolved from `entry` in `context` (absolute path). + +- `context`: The base path for module resolution, under which the entry module resolution will be conducted. +- `entry`: Specifies the module path to be used as an entry point. +- `options`: Additional configurations for the entry module. + +### DynamicEntryPlugin + + + +`DynamicEntryPlugin(context, entry)` + +Similar to `EntryPlugin` but accepts a function as the `entry` argument. This function is called during each `make` event in the build process to support dynamically determining the entry points. + +### EntryOptionPlugin + +`EntryOptionPlugin()` + +## output + +### EvalDevToolModulePlugin + +`EvalDevToolModulePlugin(options)` + +Decorates the module template by wrapping each module in a `eval` annotated with `// @sourceURL`. + +### WebWorkerTemplatePlugin + +`webworker.WebWorkerTemplatePlugin(options)` + +Chunks are loaded by `importScripts`. + +`options` are the output options. + +## source + +Plugins affecting the source code of modules. + +### ProvidePlugin + + + +`ProvidePlugin(name, request)` + +If `name` is used in a module it is filled by a module loaded by `require()`. + +### NodeTargetPlugin + + + +`node.NodeTargetPlugin()` + +The plugins should be used if you run the bundle in a Node.js environment. + +If ensures that native modules are loaded correctly even if bundled. + +## optimize + +Note that all plugins under `rspack.optimize` namespace should only be used when `mode` set to `'none'`. Otherwise you might get into trouble where plugins are applied twice. + +### LimitChunkCountPlugin + + + +`optimize.LimitChunkCountPlugin(options)` + +Merge chunks limit chunk count is lower than `options.maxChunks`. + +The overhead for each chunks is provided by `options.chunkOverhead` or defaults to 10000. Entry chunks sizes are multiplied by `options.entryChunkMultiplicator` (or 10). + +Chunks that reduce the total size the most are merged first. If multiple combinations are equal the minimal merged size wins. + +## loader + +### LoaderOptionsPlugin + +`LoaderOptionsPlugin(options)` + +### LoaderTargetPlugin + +`LoaderTargetPlugin(target)` + +## module federation + +Internal plugins used with Module Federation, which are the basis of the `ModuleFederationPlugin`. + +### ContainerPlugin + + + +`container.ContainerPlugin(options)` + +### ContainerReferencePlugin + + + +`container.ContainerReferencePlugin(options)` + +### ConsumeSharedPlugin + + + +`sharing.ConsumeSharedPlugin(options)` + +### ProvideSharedPlugin + + + +`sharing.ProvideSharedPlugin(options)` + +### SharePlugin + + + +`sharing.SharePlugin(options)` diff --git a/website/docs/zh/plugins/webpack/_meta.json b/website/docs/zh/plugins/webpack/_meta.json index 1167697d5db..667156e72a4 100644 --- a/website/docs/zh/plugins/webpack/_meta.json +++ b/website/docs/zh/plugins/webpack/_meta.json @@ -1,6 +1,5 @@ [ "index", - "entry-plugin", "define-plugin", "provide-plugin", "banner-plugin", @@ -8,6 +7,7 @@ "ignore-plugin", "progress-plugin", "externals-plugin", + "eval-source-map-dev-tool-plugin", "source-map-dev-tool-plugin", "split-chunks-plugin", "node-target-plugin", @@ -15,10 +15,10 @@ "enable-chunk-loading-plugin", "enable-library-plugin", "enable-wasm-loading-plugin", - "electron-target-plugin", "module-federation-plugin", "module-federation-plugin-v1", "environment-plugin", "limit-chunk-count-plugin", - "normal-module-replacement-plugin" + "normal-module-replacement-plugin", + "internal-plugins" ] diff --git a/website/docs/zh/plugins/webpack/electron-target-plugin.mdx b/website/docs/zh/plugins/webpack/electron-target-plugin.mdx deleted file mode 100644 index e259c2b23ac..00000000000 --- a/website/docs/zh/plugins/webpack/electron-target-plugin.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import { ApiMeta } from '@components/ApiMeta.tsx'; - -# ElectronTargetPlugin - - - -此插件用来在打包时将 Electron 的内置模块外置掉，[`externalsPresets.electron`](/config/externals#electron)、[`externalsPresets.electronMain`](/config/externals#electronmain)、[`externalsPresets.electronRenderer`](/config/externals#electronrenderer) 和 [`externalsPresets.electronPreload`](/config/externals#electronpreload) 底层使用了该插件。 - -```js -new rspack.electron.ElectronTargetPlugin(); -``` diff --git a/website/docs/zh/plugins/webpack/entry-plugin.mdx b/website/docs/zh/plugins/webpack/entry-plugin.mdx deleted file mode 100644 index 79eaa39a003..00000000000 --- a/website/docs/zh/plugins/webpack/entry-plugin.mdx +++ /dev/null @@ -1,43 +0,0 @@ -import { ApiMeta } from '@components/ApiMeta.tsx'; - -# EntryPlugin - - - -在编译时添加一个入口 chunk。该 chunk 的名称为 `options.name`，仅包含一个模块（以及依赖项）。该模块是通过 `entry` 在 `context` 下（绝对路径）解析出来的。 - -```js -new rspack.EntryPlugin(context, entry, options); -``` - -## 选项 - -### context - -入口模块的请求路径会在该 `context` 路径下解析为绝对路径。 - -- **类型：** `string` - -### entry - -入口模块的请求路径。 - -- **类型：** `string` - -### options - -调整入口模块的相关设置。 - -- **类型：** - -```ts -type EntryOptions = { - name?: string; - runtime?: EntryRuntime; - chunkLoading?: ChunkLoading; - asyncChunks?: boolean; - publicPath?: PublicPath; - baseUri?: string; - filename?: Filename; -}; -``` diff --git a/website/docs/zh/plugins/webpack/eval-source-map-dev-tool-plugin.mdx b/website/docs/zh/plugins/webpack/eval-source-map-dev-tool-plugin.mdx new file mode 100644 index 00000000000..f4affa0e89f --- /dev/null +++ b/website/docs/zh/plugins/webpack/eval-source-map-dev-tool-plugin.mdx @@ -0,0 +1,55 @@ +import WebpackLicense from '@components/webpack-license'; + + + +# EvalSourceMapDevToolPlugin + +这个插件可以更细致地控制源映射文件（source map）的生成。在特定的 [`devtool`](/config/devtool) 配置选项设置下，它也会被自动启用。 + +```js +new webpack.EvalSourceMapDevToolPlugin(options); +``` + +## 选项 + +### append + +- **类型：** `string | function` + +将给定值附加到原始资源。通常是 `#sourceMappingURL` 注释。`[url]` 会被替换成指向源映射文件的 URL。设置为 `false` 将禁止附加。 + +### module + +- **类型：** `boolean` + +指示 loader 是否应生成 source map（默认为 `true`）。 + +### columns + +- **类型：** `boolean` + +指示是否应该使用列映射（默认为 `true`）。 + +## 示例 + +### 基本使用 + +你可以使用以下代码来替换配置选项 `devtool: eval-source-map`，使用等效的自定义插件配置： + +```js +module.exports = { + // ... + devtool: false, + plugins: [new rspack.EvalSourceMapDevToolPlugin({})], +}; +``` + +### 排除 Vendor Maps + +以下代码将排除 `vendor.js` 打包文件中的任何模块的 source map： + +```js +new rspack.EvalSourceMapDevToolPlugin({ + exclude: ['vendor.js'], +}); +``` diff --git a/website/docs/zh/plugins/webpack/internal-plugins.mdx b/website/docs/zh/plugins/webpack/internal-plugins.mdx new file mode 100644 index 00000000000..13a8218735b --- /dev/null +++ b/website/docs/zh/plugins/webpack/internal-plugins.mdx @@ -0,0 +1,175 @@ +import { ApiMeta } from '@components/ApiMeta.tsx'; +import WebpackLicense from '@components/webpack-license'; + + + +# 内部使用的插件 + +这是 Rspack 内部使用的插件列表，对齐 webpack 内部使用的插件。 + +:::warning 警告 +通常你不需要关心这些插件，除非你在基于 Rspack 构建自己的编译器，或者是深入探查其内部机制。 +::: + +使用的插件的分类： + +- [environment](#environment) +- [compiler](#compiler) +- [entry](#entry) +- [output](#output) +- [source](#source) +- [optimize](#optimize) +- [loader](#loader) +- [module federation](#module-federation) + +## environment + +影响编译器环境的插件。 + +### ElectronTargetPlugin + +`electron.ElectronTargetPlugin(context)` + +为 Electron 应用中的不同上下文（如主进程、预加载脚本和渲染进程）定制外部依赖处理。 + +[`externalsPresets.electron`](/config/externals#electron)、[`externalsPresets.electronMain`](/config/externals#electronmain)、[`externalsPresets.electronRenderer`](/config/externals#electronrenderer) 和 [`externalsPresets.electronPreload`](/config/externals#electronpreload) 配置项均依赖该插件。 + +### NodeEnvironmentPlugin + +`node.NodeEnvironmentPlugin()` + +将 Node.js 风格的文件系统应用到编译器。 + +## compiler + +影响编译器的插件。 + +### ProgressPlugin + +`ProgressPlugin(handler)` + +订阅编译器钩子以获取进度信息。处理函数必须符合 `function(percentage, message)` 的签名形式。其中的 `percentage` 会被调用，并传入一个介于 0 和 1 之间的值，0 表示开始，1 表示结束。 + +## entry + +处理入口 chunk 的插件。 + +### EntryPlugin + +`EntryPlugin(context, entry, options)` + +在编译时添加一个入口 chunk。该 chunk 的名称为 `options.name`，仅包含一个模块（以及依赖项）。该模块是通过 `entry` 在 `context` 下（绝对路径）解析出来的。 + +- `context`：模块解析时的基础路径，入口模块的解析将在此路径下进行。 +- `entry`：指定要作为入口点的模块路径。 +- `options`：入口模块的额外配置。 + +### DynamicEntryPlugin + + + +`DynamicEntryPlugin(context, entry)` + +与 `EntryPlugin` 类似，但接受一个函数作为 `entry` 参数。该函数在构建过程中的每个 `make` 事件触发时调用，以支持动态决定入口点。 + +### EntryOptionPlugin + +`EntryOptionPlugin()` + +## output + +### EvalDevToolModulePlugin + +`EvalDevToolModulePlugin(options)` + +通过在每个模块中使用带有 `// @sourceURL` 注释的 `eval` 来装饰模块模板。 + +### WebWorkerTemplatePlugin + +`webworker.WebWorkerTemplatePlugin(options)` + +通过 `importScripts` 加载代码块。 + +`options` 是输出配置。 + +## source + +影响模块源代码的插件。 + +### ProvidePlugin + + + +`ProvidePlugin(name, request)` + +如果在模块中使用 `name`，则会由通过填充 `require()` 来加载它。 + +### NodeTargetPlugin + + + +`node.NodeTargetPlugin()` + +如果你在 Node.js 环境中运行打包文件，应当使用这个插件。 + +它确保即使在打包后，原生模块也能被正确加载。 + +## optimize + +请注意，只有当 `mode` 设置为 `'none'` 时，才应该使用 `rspack.optimize` 命名空间下的插件。否则，你可能会遇到插件被应用两次而导致问题的情况。 + +### LimitChunkCountPlugin + + + +`optimize.LimitChunkCountPlugin(options)` + +合并 chunk，直到 chunk 数量少于 `options.maxChunks` 所设定的上限。 + +每个 chunk 的开销由 `options.chunkOverhead` 决定，如果没有指定则默认为 10000。入口 chunk 的大小会被 `options.entryChunkMultiplicator`（或默认的 10）所乘。 + +首先合并那些能最大幅度减少总大小的 chunk。如果有多个组合能够等量减少，那么合并后大小最小的组合将会胜出。 + +## loader + +### LoaderOptionsPlugin + +`LoaderOptionsPlugin(options)` + +### LoaderTargetPlugin + +`LoaderTargetPlugin(target)` + +## module federation + +使用模块联邦（Module Federation）时内部所使用的插件，这些是 `ModuleFederationPlugin` 所依赖的基础插件。 + +### ContainerPlugin + + + +`container.ContainerPlugin(options)` + +### ContainerReferencePlugin + + + +`container.ContainerReferencePlugin(options)` + +### ConsumeSharedPlugin + + + +`sharing.ConsumeSharedPlugin(options)` + +### ProvideSharedPlugin + + + +`sharing.ProvideSharedPlugin(options)` + +### SharePlugin + + + +`sharing.SharePlugin(options)`