@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/configure/app/tools/autoprefixer.md

@@ -0,0 +1,44 @@
+# tools.autoprefixer
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+{
+  flexbox: 'no-2009',
+  // Depends on the browserslist config in the project
+  // and the `output.overrideBrowserslist` (higher priority) config
+  overrideBrowserslist: browserslist,
+}
+```
+
+You can modify the config of [autoprefixer](https://github.com/postcss/autoprefixer) by `tools.autoprefixer`.
+
+### Object Type
+
+When `tools.autoprefixer` is configured as `Object` type, it is merged with the default config through Object.assign. For example:
+
+```js
+export default {
+  tools: {
+    autoprefixer: {
+      flexbox: 'no-2009',
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.autoprefixer` is a Function, the default config is passed as the first parameter and can be directly modified or returned as the final result. For example:
+
+```js
+export default {
+  tools: {
+    autoprefixer(config) {
+      // modify flexbox config
+      config.flexbox = 'no-2009';
+    },
+  },
+};
+```

package/docs/configure/app/tools/bundler-chain.md

@@ -0,0 +1,26 @@
+# tools.bundlerChain
+
+- **Type:**
+
+```ts
+type BundlerChainFn = (
+  chain: RspackChain,
+  utils: ModifyBundlerChainUtils,
+) => Promise<void> | void;
+```
+
+- **Default:** `undefined`
+
+You can modify the Rspack configuration by configuring `tools.bundlerChain` which is type of `Function`. The function receives two parameters, the first is the original bundler chain object, and the second is an object containing some utils.
+
+:::tip What is BundlerChain
+
+Bundler chain is a chainable configuration tool implemented based on the Rspack configuration API, which you can use to modify Rspack configuration.
+
+Configurations modified via bundler chain will work on Rspack builds.
+
+:::
+
+> `tools.bundlerChain` is executed earlier than tools.rspack and thus will be overridden by changes in tools.rspack.
+
+For more information, please refer to [Rsbuild#tools.bundlerChain](https://v2.rsbuild.rs/config/tools/bundler-chain).

package/docs/configure/app/tools/css-extract.md

@@ -0,0 +1,33 @@
+# tools.cssExtract
+
+- **Type:**
+
+```ts
+type CSSExtractOptions = {
+  pluginOptions?: Rspack.CssExtractRspackPluginOptions;
+  loaderOptions?: Rspack.CssExtractRspackLoaderOptions;
+};
+```
+
+- **Default:**
+
+```js
+const defaultOptions = {
+  // The loader options
+  loaderOptions: {},
+  // The plugin options
+  pluginOptions: {
+    // The default value of cssPath is `static/css`
+    // while the default value of cssFilename is `[name].[contenthash:8].css`
+    filename: `${cssPath}/${cssFilename}`,
+    chunkFilename: `${cssPath}/async/${cssFilename}`,
+    ignoreOrder: true,
+  },
+};
+```
+
+The config of [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) can be modified through `tools.cssExtract`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.cssExtract](https://v2.rsbuild.dev/config/tools/css-extract).
+:::

package/docs/configure/app/tools/css-loader.md

@@ -0,0 +1,17 @@
+# tools.cssLoader
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  modules: rsbuildConfig.output.cssModules,
+  sourceMap: rsbuildConfig.output.sourceMap.css,
+};
+```
+
+The config of [css-loader](https://github.com/webpack-contrib/css-loader) can be modified through `tools.cssLoader`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.cssLoader](https://v2.rsbuild.dev/config/tools/css-loader).
+:::

package/docs/configure/app/tools/dev-server.md

@@ -0,0 +1,113 @@
+# tools.devServer
+
+- **Type:** `Object`
+- **Default:** `{}`
+
+The config of DevServer can be modified through `tools.devServer`.
+
+### Options
+
+#### compress
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.server.compress](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable gzip compression for served static assets.
+
+If you want to disable the gzip compression, you can set `compress` to `false`:
+
+```ts
+export default {
+  tools: {
+    devServer: {
+      compress: false,
+    },
+  },
+};
+```
+
+#### headers
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.server.headers](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
+
+Adds headers to all responses.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+#### historyApiFallback
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.server.historyApiFallback](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
+- **Type:** `boolean | ConnectHistoryApiFallbackOptions`
+- **Default:** `false`
+
+The index.html page will likely have to be served in place of any 404 responses. Enable `devServer.historyApiFallback` by setting it to `true`:
+
+```js
+export default {
+  tools: {
+    devServer: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation.
+
+#### proxy
+
+:::warning
+**Deprecated**: This configuration is deprecated, use [dev.server.proxy](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
+- **Type:** `ProxyOptions[] | Record<string, string | ProxyOptions>`
+- **Default:** `undefined`
+
+Configure proxy rules for the dev server, and forward requests to the specified service.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+};
+```
+
+#### watch
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.server.watch](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to watch files change in directories such as `mock/`, `server/`, `api/`.

package/docs/configure/app/tools/html-plugin.md

@@ -0,0 +1,41 @@
+# tools.htmlPlugin
+
+- **Type:** `boolean | Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  meta, // 对应 `html.meta` 配置
+  title, // 对应 `html.title` 配置
+  inject, // 对应 `html.inject` 配置
+  favicon, // 对应 `html.favicon` 配置
+  template, // 对应 `html.template` 配置
+  filename, // 基于 `output.distPath` 和 `entryName` 生成
+  templateParameters, // 对应 `html.templateParameters` 配置
+  chunks: [entryName],
+  minify: {
+    // generated based on `output.minify`
+    removeComments: false,
+    useShortDoctype: true,
+    keepClosingSlash: true,
+    collapseWhitespace: true,
+    removeRedundantAttributes: true,
+    removeScriptTypeAttributes: true,
+    removeStyleLinkTypeAttributes: true,
+    removeEmptyAttributes: true,
+    minifyJS, // generated based on `output.charset`, `output.legalComments` and `performance.removeConsole`
+    minifyCSS: true,
+    minifyURLs: true,
+  },
+};
+```
+
+:::warning
+SSR Application does not enable the `minify.removeComments` configuration, otherwise the SSR rendering will fail.
+:::
+
+The configs of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.htmlPlugin](https://v2.rsbuild.dev/config/tools/html-plugin).
+:::

package/docs/configure/app/tools/less.md

@@ -0,0 +1,81 @@
+# tools.less
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  lessOptions: {
+    javascriptEnabled: true,
+  },
+  // CSS Source Map enabled by default in development environment
+  sourceMap: isDev,
+};
+```
+
+You can modify the config of [less-loader](https://github.com/webpack-contrib/less-loader) via `tools.less`.
+
+### Object Type
+
+When `tools.less` is configured as `Object` type, it is merged with the default config through Object.assign in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way. For example:
+
+```js
+export default {
+  tools: {
+    less: {
+      lessOptions: {
+        javascriptEnabled: false,
+      },
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.less` 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: {
+    less(config) {
+      // Modify the config of lessOptions
+      config.lessOptions = {
+        javascriptEnabled: false,
+      };
+    },
+  },
+};
+```
+
+### Modifying Less Version
+
+In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Modern.js, you can install the desired Less version in your project and set it up using the `implementation` option of the `less-loader`.
+
+```js
+export default {
+  tools: {
+    less: {
+      implementation: require('less'),
+    },
+  },
+};
+```
+
+### Util Function
+
+#### addExcludes
+
+- **Type:** `(excludes: RegExp | RegExp[]) => void`
+
+Used to specify which files `less-loader` does not compile, You can pass in one or more regular expressions to match the path of less files, for example:
+
+```js
+export default {
+  tools: {
+    less(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```

package/docs/configure/app/tools/lightningcss-loader.md

@@ -0,0 +1,35 @@
+# tools.lightningcssLoader
+
+- **Type:** `Rspack.LightningcssLoaderOptions | Function | boolean`
+- **Default:** `Rspack.LightningcssLoaderOptions | Function | boolean`
+
+You can configure [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) through `tools.lightningcssLoader`.
+
+## Enable loader
+
+Set `tools.lightningcssLoader` to `true` to enable Rsbuild's built-in `lightningcss-loader`:
+
+```js
+export default {
+  tools: {
+    lightningcssLoader: true,
+  },
+};
+```
+
+At this time, the default configuration is as follows:
+
+```js
+const defaultOptions = {
+  // use current browserslist config
+  targets: browserslist,
+  // minify is enabled when output.injectStyles is true and in production mode
+  minify: config.mode === 'production' && config.output.injectStyles,
+};
+```
+
+It should be noted that when `lightningcss-loader` is turned on, `postcss-loader` will be turned off by default.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.lightningcssLoader](https://v2.rsbuild.dev/config/tools/lightningcss-loader).
+:::

package/docs/configure/app/tools/minify-css.md

@@ -0,0 +1,53 @@
+# tools.minifyCss
+
+- **Type:** `Object | Function | undefined`
+- **Default:**
+
+```js
+const defaultOptions = {
+  minimizerOptions: {
+    preset: [
+      'default',
+      {
+        mergeLonghand: false,
+      },
+    ],
+  },
+};
+```
+
+When building for production, Modern.js will minimize the CSS code through [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin). The config of [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) can be modified via `tools.minifyCss`.
+
+### Object Type
+
+When `tools.minifyCss` is `Object` type, it will be merged with the default config via `Object.assign`.
+
+For example, modify the `preset` config of [cssnano](https://cssnano.co/):
+
+```js
+export default {
+  tools: {
+    minifyCss: {
+      minimizerOptions: {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.minifyCss` 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: {
+    minifyCss: options => {
+      options.minimizerOptions = {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    }
+  }
+};
+```

package/docs/configure/app/tools/postcss.md

@@ -0,0 +1,34 @@
+# tools.postcss
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  postcssOptions: {
+    plugins: [
+      // The following plugins are enabled by default
+      require('postcss-nesting'),
+      require('postcss-media-minmax'),
+      require('postcss-flexbugs-fixes'),
+      require('autoprefixer')({
+        flexbox: 'no-2009',
+      }),
+      // The following plugins are only enabled when compatible with legacy browsers
+      require('postcss-custom-properties'),
+      require('postcss-initial'),
+      require('postcss-page-break'),
+      require('postcss-font-variant'),
+    ],
+    sourceMap: isDev,
+  },
+};
+```
+
+Modern.js integrates PostCSS by default, you can configure [postcss-loader](https://github.com/webpack-contrib/postcss-loader) through `tools.postcss`.
+
+It should be noted that when you enable the `tools.lightningcss` configuration, PostCSS will be disabled by default, including `postcss-loader` and its default plugins.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.postcss](https://v2.rsbuild.dev/config/tools/postcss).
+:::

package/docs/configure/app/tools/rspack.md

@@ -0,0 +1,10 @@
+# tools.rspack
+
+- **Type:** `Rspack.Configuration | Function | undefined`
+- **Default:** `undefined`
+
+`tools.rspack` is used to configure [Rspack](https://rspack.rs/).
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.rspack](https://v2.rsbuild.dev/config/tools/rspack).
+:::

package/docs/configure/app/tools/sass.md

@@ -0,0 +1,78 @@
+# tools.sass
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```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/configure/app/tools/style-loader.md

@@ -0,0 +1,10 @@
+# tools.styleLoader
+
+- **Type:** `Object | Function`
+- **Default:** `{}`
+
+The config of [style-loader](https://github.com/webpack-contrib/style-loader) can be set through `tools.styleLoader`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - tools.styleLoader](https://v2.rsbuild.dev/config/tools/style-loader).
+:::

package/docs/configure/app/tools/swc.md

@@ -0,0 +1,65 @@
+# tools.swc
+
+- **Type:** `Object | Function`
+- **Default:** `undefined`
+
+## Introduction
+
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+Modern.js has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.
+
+:::tip
+When using Rspack as the bundler, SWC will be used for transpiling and compression by default, so you don't need to install or configure the SWC plugin.
+:::
+
+## Used in Rspack mode
+
+You can set the options of [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) through `tools.swc`.
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc: {
+      jsc: {
+        externalHelpers: false,
+      },
+    },
+  },
+});
+```
+
+For more usage, please refer to [Rsbuild - tools.swc](https://v2.rsbuild.rs/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://v2.rsbuild.rs/guide/configuration/swc#swc-plugin-version).