@modern-js/main-doc 2.60.0 → 2.60.1

package/docs/en/configure/app/tools/rspack.mdx

@@ -1,9 +1,15 @@
 ---
 title: rspack
+configName: tools.rspack
 ---
 
 # tools.rspack
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/rspack.md';
+- **Type:** `Rspack.Configuration | Function | undefined`
+- **Default:** `undefined`
 
-<Main />
+`tools.rspack` is used to configure [Rspack](https://rspack.dev/).
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/tools/sass.mdx

@@ -4,6 +4,79 @@ title: sass
 
 # tools.sass
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/sass.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  // CSS Source Map enabled by default in development environment
+  sourceMap: isDev,
+};
+```
+
+You can modify the config of [sass-loader](https://github.com/webpack-contrib/sass-loader) via `tools.sass`.
+
+### Object Type
+
+When `tools.sass` is `Object` type, it is merged with the default config through Object.assign. It should be noted that `sassOptions` is merged through deepMerge in a deep way.
+
+For example:
+
+```js
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.sass` is a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For Example:
+
+```js
+export default {
+  tools: {
+    sass(config) {
+      // Modify sourceMap config
+      config.additionalData = async (content, loaderContext) => {
+        // ...
+      };
+    },
+  },
+};
+```
+
+### Modifying Sass Version
+
+In some scenarios, if you need to use a specific version of Sass instead of the built-in Dart Sass v1 in Modern.js, you can install the desired Sass version in your project and set it up using the `implementation` option of the `sass-loader`.
+
+```js
+export default {
+  tools: {
+    sass: {
+      implementation: require('sass'),
+    },
+  },
+};
+```
+
+### Utility Function
+
+#### addExcludes
+
+- **Type:** `(excludes: RegExp | RegExp[]) => void`
+
+Used to specify which files `sass-loader` does not compile, You can pass in one or more regular expressions to match the path of sass files, for example:
+
+```js
+export default {
+  tools: {
+    sass(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```

package/docs/en/configure/app/tools/style-loader.mdx

@@ -1,9 +1,15 @@
 ---
 title: styleLoader
+configName: tools.styleLoader
 ---
 
 # tools.styleLoader
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/styleLoader.md';
+- **Type:** `Object | Function`
+- **Default:** `{}`
 
-<Main />
+The config of [style-loader](https://github.com/webpack-contrib/style-loader) can be set through `tools.styleLoader`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/tools/styled-components.mdx

@@ -4,6 +4,52 @@ title: styledComponents
 
 # tools.styledComponents
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/styledComponents.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+{
+  displayName: true,
+  // `isSSR` is true in SSR build
+  ssr: isSSR,
+  // `pure` is enabled in production to reduce bundle size
+  pure: isProd,
+  transpileTemplateLiterals: true,
+}
+```
+
+`tools.styledComponents` config is corresponding to [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components), or [@swc/plugin-styled-components](https://github.com/swc-project/plugins/tree/main/packages/styled-components) when using SWC plugin.
+
+When the value is an Object, use the Object.assign function to merge with the default config. For example:
+
+```js
+export default {
+  tools: {
+    styledComponents: {
+      pure: false,
+    },
+  },
+};
+```
+
+When the config is a Function, the first parameter is the default configuration, and the second parameter provides some utility functions that can be called directly:
+
+```js
+export default {
+  tools: {
+    styledComponents(config) {
+      config.pure = false;
+    },
+  },
+};
+```
+
+The feature is enabled by default, and you can configure `tools.styledComponents` to `false` to disable this behavior, which can improve build performance:
+
+```js
+export default {
+  tools: {
+    styledComponents: false,
+  },
+};
+```

package/docs/en/configure/app/tools/swc.mdx

@@ -9,7 +9,7 @@ title: swc
 
 ## Introduction
 
-import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
+import SWC from '@site-docs-en/components/swc.mdx';
 
 <SWC />
 
@@ -37,9 +37,40 @@ export default defineConfig<'rspack'>({
 
 For more usage, please refer to [Rsbuild - tools.swc](https://rsbuild.dev/config/tools/swc).
 
+### Register SWC Plugin
+
+Modern.js supports registering SWC's Wasm plugin through `tools.swc`, such as registering [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components):
+
+```ts
+export default {
+  tools: {
+    swc: {
+      jsc: {
+        experimental: {
+          plugins: [['@swc/plugin-styled-components', {}]],
+        },
+      },
+    },
+  },
+};
+```
+
+Please note that the SWC plugin is still an experimental feature, and the SWC Wasm plugin is currently not backward compatible. The version of the SWC plugin is closely tied to the version of swc_core that Rspack depends on.
+
+This means that you must to choose an SWC plugin that matches the current version of swc_core to ensure that it works properly. If the version of the SWC plugin you are using does not match the version of swc_core that Rspack depends on, Rspack will throw the following error during the build process:
+
+```
+1: failed to run Wasm plugin transform. Please ensure the version of `swc_core`
+   used by the plugin is compatible with the host runtime.
+```
+
+If you encounter the above issues, a common solution is to upgrade both the Modern.js and SWC plugins to the latest versions.
+
+For details, please refer to [Rsbuild - SWC Plugin Version](https://rsbuild.dev/guide/basic/configure-swc#swc-plugin-version).
+
 ## Used in Webpack mode
 
-import EnableSWC from '@modern-js/builder-doc/docs/en/shared/enableSwc.md';
+import EnableSWC from '@site-docs-en/components/enableSwc.mdx';
 
 <EnableSWC />
 

package/docs/en/configure/app/tools/terser.mdx

@@ -4,6 +4,53 @@ title: terser
 
 # tools.terser
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/terser.md';
+- **Type:** `Object | Function | undefined`
+- **Default:**
 
-<Main />
+```js
+const defaultTerserOptions = {
+  terserOptions: {
+    mangle: {
+      safari10: true,
+    },
+  },
+};
+```
+
+- **Bundler:** `only support webpack`
+
+When building for production, Modern.js will minimize the JavaScript code through [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin). The config of [terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin) can be modified via `tools.terser`.
+
+### Object Type
+
+When `tools.terser` is `Object` type, it will be merged with the default config via `Object.assign`.
+
+For example, to exclude some files from minification:
+
+```js
+export default {
+  tools: {
+    terser: {
+      exclude: /\/excludes/,
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.terser` is `Function` type, the default config is passed in as the first parameter, the config object can be modified directly, or a value can be returned as the final result.
+
+```js
+export default {
+  tools: {
+    terser: opts => {
+      opts.exclude = /\/excludes/;
+    },
+  },
+};
+```
+
+:::tip Disable code minification
+If you need to disable code minification, you can use the [output.disableMinimize](https://modernjs.dev/builder/en/api/config-output.html#outputdisableminimize) configuration.
+:::

package/docs/en/configure/app/tools/ts-checker.mdx

@@ -4,6 +4,53 @@ title: tsChecker
 
 # tools.tsChecker
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/tsChecker.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  typescript: {
+    // avoid OOM issue
+    memoryLimit: 8192,
+    // use tsconfig of user project
+    configFile: tsconfigPath,
+    // use typescript of user project
+    typescriptPath: require.resolve('typescript'),
+  },
+  issue: {
+    exclude: [
+      { file: '**/*.(spec|test).ts' },
+      { file: '**/node_modules/**/*' },
+    ],
+  },
+  logger: {
+    log() {
+      // do nothing
+      // we only want to display error messages
+    },
+    error(message: string) {
+      console.error(message.replace(/ERROR/g, 'Type Error'));
+    },
+  },
+},
+```
+
+By default, the [@rsbuild/plugin-type-check](https://rsbuild.dev/plugins/list/plugin-type-check) is enabled for type checking. You can use `output.disableTsChecker` config to disable it.
+
+## Example
+
+When the value of `tsChecker` is of type Object, it will be deeply merged with the default configuration.
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      issue: {
+        exclude: [({ file = '' }) => /[\\/]some-folder[\\/]/.test(file)],
+      },
+    },
+  },
+};
+```
+
+> Please refer to [@rsbuild/plugin-type-check](https://rsbuild.dev/plugins/list/plugin-type-check) for more details.

package/docs/en/configure/app/tools/ts-loader.mdx

@@ -4,6 +4,67 @@ title: tsLoader
 
 # tools.tsLoader
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/tsLoader.md';
+- **Type:** `Object | Function | undefined`
+- **Default:** `undefined`
+- **Bundler:** `only support webpack`
 
-<Main />
+:::warning Alternatives for ts-loader
+Using [babel-loader](https://modernjs.dev/builder/en/guide/basic/typescript.html#why-babel-is-the-default-option) or [Rspack](https://modernjs.dev/en/guide/advanced/rspack-start.html) instead of ts-loader can significantly improve compilation speed and provide better extendability.
+
+ts-loader cannot be used with certain features such as [source.transformImport](https://modernjs.dev/en/configure/app/source/transform-import.html) and [tools.styledComponents](https://modernjs.dev/en/configure/app/tools/styled-components.html) provided by Babel & SWC.
+:::
+
+`ts-loader` is not enabled by default in the project. When `tools.tsLoader` is not undefined, builder will use ts-loader instead of babel-loader to compile TypeScript code.
+
+### Object Type
+
+When this value is an Object, it is merged with the default configuration via Object.assign.
+
+The default configuration is as follows:
+
+```json
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "ESNext"
+  },
+  "transpileOnly": true,
+  "allowTsInNodeModules": true
+}
+```
+
+You can override the default configuration via the `tools.tsLoader` configuration option:
+
+```ts
+export default {
+  tools: {
+    tsLoader: {
+      allowTsInNodeModules: false,
+    },
+  },
+};
+```
+
+### Function Type
+
+When this value is a Function, the default configuration is passed in as the first parameter, the configuration object can be modified directly, or an object can be returned as the final configuration.The second parameter is the util functions to modify the `ts-loader` configuration. For example:
+
+```ts
+export default {
+  tools: {
+    tsLoader: opts => {
+      opts.allowTsInNodeModules = false;
+    },
+  },
+};
+```
+
+### Util Functions
+
+#### addIncludes
+
+Deprecated, please use [source.include](https://modernjs.dev/en/configure/app/source/include.html) instead, both have the same functionality.
+
+#### addExcludes
+
+Deprecated, please use [source.exclude](https://modernjs.dev/en/configure/app/source/exclude.html) instead, both have the same functionality.

package/docs/en/configure/app/tools/webpack-chain.mdx

@@ -4,6 +4,243 @@ title: webpackChain
 
 # tools.webpackChain
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/webpackChain.md';
+- **Type:** `Function | undefined`
+- **Default:** `undefined`
+- **Bundler:** `only support webpack`
 
-<Main />
+You can modify the webpack configuration by configuring `tools.webpackChain` which is type of `Function`. The function receives two parameters, the first is the original webpack chain object, and the second is an object containing some utils.
+
+Compared with `tools.webpack`, **webpack-chain not only supports chained calls, but also can locate built-in Rule or Plugin based on aliases, so as to achieve precise config modification**. We recommend using `tools.webpackChain` instead of `tools.webpack`.
+
+> `tools.webpackChain` is executed earlier than tools.webpack and thus will be overridden by changes in `tools.webpack`.
+
+### Utils
+
+#### env
+
+- **Type:** `'development' | 'production' | 'test'`
+
+The `env` parameter can be used to determine whether the current environment is development, production or test. For example:
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { env }) => {
+      if (env === 'development') {
+        chain.devtool('cheap-module-eval-source-map');
+      }
+    },
+  },
+};
+```
+
+#### isProd
+
+- **Type:** `boolean`
+
+The `isProd` parameter can be used to determine whether the current environment is production. For example:
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isProd }) => {
+      if (isProd) {
+        chain.devtool('source-map');
+      }
+    },
+  },
+};
+```
+
+#### target
+
+- **Type:** `'web' | 'node' | 'modern-web' | 'web-worker'`
+
+The `target` parameter can be used to determine the current environment. For example:
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { target }) => {
+      if (target === 'node') {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### isServer
+
+- **Type:** `boolean`
+
+Determines whether the target environment is `node`, equivalent to `target === 'node'`.
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isServer }) => {
+      if (isServer) {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### isWebWorker
+
+- **Type:** `boolean`
+
+Determines whether the target environment is `web-worker`, equivalent to `target === 'web-worker'`.
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isWebWorker }) => {
+      if (isWebWorker) {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### webpack
+
+- **Type:** `typeof import('webpack')`
+
+The webpack instance. For example:
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { webpack }) => {
+      chain.plugin('my-progress').use(webpack.ProgressPlugin);
+    },
+  },
+};
+```
+
+#### HtmlWebpackPlugin
+
+- **Type:** `typeof import('html-webpack-plugin')`
+
+The HtmlWebpackPlugin instance:
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { HtmlWebpackPlugin }) => {
+      console.log(HtmlWebpackPlugin);
+    },
+  },
+};
+```
+
+#### CHAIN_ID
+
+Some common Chain IDs are predefined in the Modern.js, and you can use these IDs to locate the built-in Rule or Plugin.
+
+:::tip
+Please note that some of the rules or plugins listed below are not available by default. They will only be included in the webpack configuration when you enable specific options or register certain plugins.
+
+For example, the `RULE.STYLUS` rule exists only when the Stylus plugin is registered.
+:::
+
+#### CHAIN_ID.RULE
+
+| ID            | Description                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `RULE.JS`     | Rule for `js`                                                                               |
+| `RULE.TS`     | Rule for `ts`                                                                               |
+| `RULE.CSS`    | Rule for `css`                                                                              |
+| `RULE.LESS`   | Rule for `less`                                                                             |
+| `RULE.SASS`   | Rule for `sass`                                                                             |
+| `RULE.STYLUS` | Rule for `stylus`(requires [Stylus plugin](https://rsbuild.dev/plugins/list/plugin-stylus)) |
+| `RULE.SVG`    | Rule for `svg`                                                                              |
+| `RULE.PUG`    | Rule for `pug`                                                                              |
+| `RULE.TOML`   | Rule for `toml`                                                                             |
+| `RULE.YAML`   | Rule for `yaml`                                                                             |
+| `RULE.WASM`   | Rule for `WASM`                                                                             |
+| `RULE.NODE`   | Rule for `node`                                                                             |
+| `RULE.FONT`   | Rule for `font`                                                                             |
+| `RULE.IMAGE`  | Rule for `image`                                                                            |
+| `RULE.MEDIA`  | Rule for `media`                                                                            |
+
+#### CHAIN_ID.ONE_OF
+
+`ONE_OF.XXX` can match a certain type of rule in the rule array.
+
+| ID                  | Description                                                        |
+| ------------------- | ------------------------------------------------------------------ |
+| `ONE_OF.SVG`        | Rules for SVG, automatic choice between data URI and separate file |
+| `ONE_OF.SVG_URL`    | Rules for SVG, output as a separate file                           |
+| `ONE_OF.SVG_INLINE` | Rules for SVG, inlined into bundles as data URIs                   |
+| `ONE_OF.SVG_ASSETS` | Rules for SVG, automatic choice between data URI and separate file |
+
+#### CHAIN_ID.USE
+
+`USE.XXX` can match a certain loader.
+
+| ID                                | Description                                    |
+| --------------------------------- | ---------------------------------------------- |
+| `USE.TS`                          | correspond to `ts-loader`                      |
+| `USE.CSS`                         | correspond to `css-loader`                     |
+| `USE.LESS`                        | correspond to `less-loader`                    |
+| `USE.SASS`                        | correspond to `sass-loader`                    |
+| `USE.STYLUS`                      | correspond to `stylus-loader`                  |
+| `USE.PUG`                         | correspond to `pug-loader`                     |
+| `USE.VUE`                         | correspond to `vue-loader`                     |
+| `USE.TOML`                        | correspond to `toml-loader`                    |
+| `USE.YAML`                        | correspond to `yaml-loader`                    |
+| `USE.NODE`                        | correspond to `node-loader`                    |
+| `USE.URL`                         | correspond to `url-loader`                     |
+| `USE.SVGR`                        | correspond to `@svgr/webpack`                  |
+| `USE.BABEL`                       | correspond to `babel-loader`                   |
+| `USE.STYLE`                       | correspond to `style-loader`                   |
+| `USE.POSTCSS`                     | correspond to `postcss-loader`                 |
+| `USE.CSS_MODULES_TS`              | correspond to `css-modules-typescript-loader`  |
+| `USE.MINI_CSS_EXTRACT`            | correspond to `mini-css-extract-plugin.loader` |
+| `USE.RESOLVE_URL_LOADER_FOR_SASS` | correspond to `resolve-url-loader`             |
+
+#### CHAIN_ID.PLUGIN
+
+`PLUGIN.XXX` can match a certain webpack plugin.
+
+| ID                             | Description                                                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `PLUGIN.HMR`                   | correspond to `HotModuleReplacementPlugin`                                                                     |
+| `PLUGIN.COPY`                  | correspond to `CopyWebpackPlugin`                                                                              |
+| `PLUGIN.HTML`                  | correspond to `HtmlWebpackPlugin`, you need to splice the entry name when using: `${PLUGIN.HTML}-${entryName}` |
+| `PLUGIN.DEFINE`                | correspond to `DefinePlugin`                                                                                   |
+| `PLUGIN.IGNORE`                | correspond to `IgnorePlugin`                                                                                   |
+| `PLUGIN.BANNER`                | correspond to `BannerPlugin`                                                                                   |
+| `PLUGIN.PROGRESS`              | correspond to `Webpackbar`                                                                                     |
+| `PLUGIN.APP_ICON`              | correspond to `AppIconPlugin`                                                                                  |
+| `PLUGIN.MANIFEST`              | correspond to `WebpackManifestPlugin`                                                                          |
+| `PLUGIN.TS_CHECKER`            | correspond to `ForkTsCheckerWebpackPlugin`                                                                     |
+| `PLUGIN.INLINE_HTML`           | correspond to `InlineChunkHtmlPlugin`                                                                          |
+| `PLUGIN.BUNDLE_ANALYZER`       | correspond to `WebpackBundleAnalyzer`                                                                          |
+| `PLUGIN.MINI_CSS_EXTRACT`      | correspond to `MiniCssExtractPlugin`                                                                           |
+| `PLUGIN.VUE_LOADER_PLUGIN`     | correspond to `VueLoaderPlugin`                                                                                |
+| `PLUGIN.REACT_FAST_REFRESH`    | correspond to `ReactFastRefreshPlugin`                                                                         |
+| `PLUGIN.NODE_POLYFILL_PROVIDE` | correspond to `ProvidePlugin` for node polyfills                                                               |
+| `PLUGIN.SUBRESOURCE_INTEGRITY` | correspond to `webpack-subresource-integrity`                                                                  |
+| `PLUGIN.ASSETS_RETRY`          | correspond to webpack static asset retry plugin                                                     |
+| `PLUGIN.AUTO_SET_ROOT_SIZE`    | correspond to automatically set root font size plugin                                               |
+
+#### CHAIN_ID.MINIMIZER
+
+`MINIMIZER.XXX` can match a certain minimizer.
+
+| ID                  | Description                               |
+| ------------------- | ----------------------------------------- |
+| `MINIMIZER.JS`      | correspond to `TerserWebpackPlugin`       |
+| `MINIMIZER.CSS`     | correspond to `CssMinimizerWebpackPlugin` |
+| `MINIMIZER.ESBUILD` | correspond to `ESBuildPlugin`             |
+| `MINIMIZER.SWC`     | correspond to `SwcWebpackPlugin`          |
+
+### Examples
+
+For usage examples, please refer to: [WebpackChain usage examples](https://modernjs.dev/builder/en/guide/advanced/custom-webpack-config.html#webpack-chain-basics).