@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.1 → 3.5.0-ultramodern.100

package/docs/configure/app/source/react-compiler.mdx

@@ -0,0 +1,72 @@
+---
+title: reactCompiler
+---
+
+# source.reactCompiler
+
+- **Type:** `boolean | ReactCompilerOptions`
+- **Default:** `undefined` (disabled)
+
+Whether to enable [React Compiler](https://react.dev/learn/react-compiler). React Compiler is a build-time tool that optimizes re-rendering performance of React applications through automatic memoization.
+
+Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
+
+:::tip
+This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
+:::
+
+## Example
+
+### Enable React Compiler (React 19)
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: true,
+  },
+});
+```
+
+### Using with React 18
+
+The compiled output targets React 19 by default. To use it in React 18 projects, you need to:
+
+1. Install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) as a **runtime dependency** (the compiled output references it at runtime):
+
+```bash
+npm add react-compiler-runtime
+```
+
+2. Specify the React version via `target`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      target: '18',
+    },
+  },
+});
+```
+
+### Customize compilation behavior
+
+When passing an object, the options are the same as Rspack's `jsc.transform.reactCompiler`. For example, use `compilationMode: 'annotation'` to only compile functions annotated with the `"use memo"` directive:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    reactCompiler: {
+      compilationMode: 'annotation',
+    },
+  },
+});
+```
+
+For the complete list of options, see [Rsbuild - reactCompiler](https://rsbuild.rs/plugins/list/plugin-react#reactcompiler) and the [React Compiler configuration docs](https://react.dev/reference/react-compiler/configuration).

package/docs/configure/app/source/transform-import.mdx

@@ -0,0 +1,31 @@
+---
+title: transformImport
+---
+
+# source.transformImport
+
+Transform the import path, which can be used to modularly import the subpath of third-party packages. The functionality is similar to [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import)。
+
+- **Type:**
+
+```ts
+type TransformImport =
+  | false
+  | Array<{
+      libraryName: string;
+      libraryDirectory?: string;
+      style?: string | boolean;
+      styleLibraryDirectory?: string;
+      camelToDashComponentName?: boolean;
+      transformToDefaultImport?: boolean;
+      customName?: string;
+      customStyleName?: string;
+    }>
+  | Function;
+```
+
+- **Default:** `undefined`
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.transformImport" />

package/docs/configure/app/split-chunks.mdx

@@ -0,0 +1,17 @@
+# splitChunks
+
+- **Type:**
+
+```ts
+type SplitChunksConfig =
+  | (Rspack.OptimizationSplitChunksOptions & {
+      preset?: SplitChunksPreset;
+    })
+  | false;
+```
+
+`splitChunks` is used to configure Rsbuild's chunk splitting strategy.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="splitChunks" />

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

@@ -0,0 +1,48 @@
+---
+title: autoprefixer
+---
+
+# 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.mdx

@@ -0,0 +1,30 @@
+---
+title: bundlerChain
+---
+
+# 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.mdx

@@ -0,0 +1,37 @@
+---
+title: cssExtract
+---
+
+# 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`.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.cssExtract" />

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

@@ -0,0 +1,21 @@
+---
+title: cssLoader
+---
+
+# 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`.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.cssLoader" />

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

@@ -0,0 +1,117 @@
+---
+title: devServer
+---
+
+# 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.mdx

@@ -0,0 +1,45 @@
+---
+title: htmlPlugin
+---
+
+# 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`.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.htmlPlugin" />

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

@@ -0,0 +1,85 @@
+---
+title: less
+---
+
+# 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.mdx

@@ -0,0 +1,39 @@
+---
+title: lightningcssLoader
+---
+
+# 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.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.lightningcssLoader" />

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

@@ -0,0 +1,57 @@
+---
+title: minifyCss
+---
+
+# 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.mdx

@@ -0,0 +1,38 @@
+---
+title: postcss
+---
+
+# 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.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.postcss" />

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

@@ -0,0 +1,14 @@
+---
+title: rspack
+---
+
+# tools.rspack
+
+- **Type:** `Rspack.Configuration | Function | undefined`
+- **Default:** `undefined`
+
+`tools.rspack` is used to configure [Rspack](https://rspack.rs/).
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.rspack" />