@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/configure/app/output/override-browserslist.md

@@ -0,0 +1,22 @@
+# output.overrideBrowserslist
+
+- **Type:** `string[] | undefined`
+- **Default:**
+
+```ts
+const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
+  web: ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
+  node: ['node >= 14'],
+  'web-worker': ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
+};
+```
+
+Specifies the range of target browsers that the project is compatible with.
+
+This value will be used by [SWC](https://github.com/swc-project/swc) and [autoprefixer](https://github.com/postcss/autoprefixer) to identify the JavaScript syntax that need to be transformed and the CSS browser prefixes that need to be added.
+
+For other configuration methods and configuration priorities, please refer to the [Browserslist configuration](/guides/advanced-features/compatibility.md).
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.overrideBrowserslist](https://v2.rsbuild.dev/config/output/override-browserslist).
+:::

package/docs/configure/app/output/polyfill.md

@@ -0,0 +1,12 @@
+# output.polyfill
+
+- **Type:** `'entry' | 'usage' | 'ua' | 'off'`
+- **Default:** `'entry'`
+
+Via `output.polyfill` you can configure how the polyfill is injected.
+
+Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information. For detailed usage instructions, please refer to [Polyfill At Runtime](https://modernjs.dev/en/guides/advanced-features/compatibility.html#polyfill-at-runtime).
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.polyfill](https://v2.rsbuild.dev/config/output/polyfill).
+:::

package/docs/configure/app/output/source-map.md

@@ -0,0 +1,30 @@
+# output.sourceMap
+
+- **Type:**
+
+```ts
+type SourceMap =
+  | boolean
+  | {
+      js?: Rspack.Configuration['devtool'];
+      css?: boolean;
+    };
+```
+
+- **Default:**
+
+```ts
+const defaultSourceMap = {
+  js: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
+  css: isDev,
+};
+```
+
+When `output.sourceMap` is not configured, the source map generation rules of Modern.js are different from Rsbuild:
+
+- In the development mode, JS and CSS source maps are generated for development debugging.
+- In the production mode, JS source maps are generated for stack trace backtracking, and CSS source maps are not generated to provide the best build performance.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.sourceMap](https://v2.rsbuild.dev/config/output/source-map).
+:::

package/docs/configure/app/output/split-route-chunks.md

@@ -0,0 +1,16 @@
+# output.splitRouteChunks
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+When using convention-based routing, the framework will split js and css based on the route to load on demand. If your project does not want to split js and css based on routes, you can set this option to `false`.
+
+Example:
+
+```ts
+export default {
+  output: {
+    splitRouteChunks: false,
+  },
+}
+```

package/docs/configure/app/output/ssg.md

@@ -0,0 +1,81 @@
+# output.ssg
+
+- **Type:** `boolean | object`
+- **Default Value:** `undefined`
+
+Configuration to enable the application’s SSG (Static Site Generation) feature.
+
+:::tip Enabling SSG
+This configuration takes effect only when SSG is enabled. Please read the [Static Site Generation](/guides/basic-features/render/ssg.md) documentation to understand how to enable SSG and its use cases.
+
+:::
+
+:::info Recommended Reading
+The SSG feature is closely related to routing. It is recommended to understand the [routing solution](/guides/basic-features/routes/routes.md) before using SSG.
+
+:::
+
+:::info
+
+- Use `output.ssg` for single-entry apps.
+- For multi-entry apps, prefer `output.ssgByEntries`.
+- If `output.ssg` is `true` and `output.ssgByEntries` is not set, all routes under all entries are treated as SSG routes.
+
+:::
+
+## Boolean Type
+
+When this configuration is set to `true`, the SSG feature will be enabled for all entries by default. For **manual routing**, the root route of the entry will be rendered. For **conventional routing**, each route in the entry will be rendered.
+
+```js
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+});
+```
+
+## Object Type
+
+When the value type is `Object`, the following attributes can be configured.
+
+### Configuration Type
+
+```ts
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, any>;
+    };
+
+type SSGOptions = {
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
+```
+
+### Example
+
+In the example configuration below, SSG will render the pages corresponding to the `/`, `/about`, and `/user/:id` routes.
+
+For the `/user/:id` route, `cookies` will be added to the request headers.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        '/',
+        '/about',
+        {
+          url: '/user/modernjs',
+          headers: {
+            cookies: 'name=modernjs',
+          },
+        },
+      ],
+    },
+  },
+});
+```

package/docs/configure/app/output/ssgByEntries.md

@@ -0,0 +1,90 @@
+# output.ssgByEntries
+
+- **Type:** `Record<string, boolean | object>`
+- **Default Value:** `undefined`
+
+Configure SSG per entry for multi-entry applications.
+
+:::info
+
+- Use `output.ssg` for single-entry apps.
+- For multi-entry apps, prefer `output.ssgByEntries`.
+- If `output.ssg` is `true` and `output.ssgByEntries` is not set, all routes under all entries are treated as SSG routes.
+
+:::
+
+## Configuration Type
+
+```ts
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, any>;
+    };
+
+type SSGOptions = {
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
+
+// ssgByEntries type
+type SSGMultiEntryOptions = Record<string, boolean | SSGOptions>;
+```
+
+## Examples
+
+### Enable SSG for some entries
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: true,
+      admin: false,
+    },
+  },
+});
+```
+
+### Configure routes per entry
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        routes: ['/', '/about', '/user/modernjs'],
+      },
+      admin: {
+        routes: ['/', '/dashboard'],
+      },
+    },
+  },
+});
+```
+
+### Configure headers per entry or route
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        headers: {
+          'x-tt-env': 'ppe_modernjs',
+        },
+        routes: [
+          '/',
+          {
+            url: '/about',
+            headers: {
+              from: 'modern-website',
+            },
+          },
+        ],
+      },
+    },
+  },
+});
+```

package/docs/configure/app/output/svg-default-export.md

@@ -0,0 +1,30 @@
+# output.svgDefaultExport
+
+- **Type:** `'url' | 'component'`
+- **Default:** `'url'`
+
+`output.svgDefaultExport` is used to configure the default export type of SVG files.
+
+When `output.svgDefaultExport` is set to `url` , the default export of SVG files is the URL of the file. For example:
+
+```js
+import logo from './logo.svg';
+
+console.log(logo); // => asset url
+```
+
+When `output.svgDefaultExport` is set to `component` , the default export of SVG files is the React component of the file. For example:
+
+```js
+import Logo from './logo.svg';
+
+console.log(Logo); // => React Component
+```
+
+At this time, you can also specify the `?url` query to import the URL, for example:
+
+```js
+import logo from './logo.svg?url';
+
+console.log(logo); // => asset url
+```

package/docs/configure/app/output/temp-dir.md

@@ -0,0 +1,20 @@
+# output.tempDir
+
+- **Type:** `string`
+- **Default:** `''`
+
+When developing or building a project, Modern.js generates real Rspack entries and HTML templates, placing them in a temporary directory.
+
+If you want to start a project with multiple configurations at the same time, you can use this configuration to generate files in different temporary directories to avoid interference with each other.
+
+The configuration can be a relative or absolute path, but paths outside the project should be avoided.
+
+Example:
+
+```ts
+export default {
+  output: {
+    tempDir: path.join('node_modules', '.temp-dir'),
+  },
+};
+```

package/docs/configure/app/performance/build-cache.md

@@ -0,0 +1,39 @@
+# performance.buildCache
+
+- **Type:**
+
+```ts
+type BuildCacheConfig =
+  | {
+      /**
+       * Base directory for the filesystem cache.
+       */
+      cacheDirectory?: string;
+      /**
+       * Set different cache names based on cacheDigest content.
+       */
+      cacheDigest?: Array<string | undefined>;
+      /**
+       * An arrays of additional code dependencies for the build.
+       * Rspack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.
+       */
+      buildDependencies?: string[];
+    }
+  | boolean;
+```
+
+Controls the caching behavior during the build process.
+
+Modern.js will enable build cache by default to improve the compile speed. You can disable the build cache by setting it to `false`:
+
+```js
+export default {
+  performance: {
+    buildCache: false,
+  },
+};
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.buildCache](https://v2.rsbuild.dev/config/performance/build-cache).
+:::

package/docs/configure/app/performance/chunk-split.md

@@ -0,0 +1,40 @@
+# performance.chunkSplit
+
+- **Type:** `Object`
+- **Default:** `{ strategy: 'split-by-experience' }`
+
+`performance.chunkSplit` is used to configure the chunk splitting strategy. The type of `ChunkSplit` is as follows:
+
+```ts
+type ForceSplitting = RegExp[] | Record<string, RegExp>;
+
+interface BaseChunkSplit {
+  strategy?:
+    | 'split-by-module'
+    | 'split-by-experience'
+    | 'all-in-one'
+    | 'single-vendor';
+  override?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+interface SplitBySize {
+  strategy?: 'split-by-size';
+  minSize?: number;
+  maxSize?: number;
+  override?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+interface SplitCustom {
+  strategy?: 'custom';
+  splitChunks?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.chunkSplit](https://v2.rsbuild.dev/config/performance/chunk-split).
+:::

package/docs/configure/app/performance/dns-prefetch.md

@@ -0,0 +1,15 @@
+# performance.dnsPrefetch
+
+- **Type:** `undefined | string[]`
+
+- **Default:** `undefined`
+
+Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin, refer to [dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch).
+
+After this property is set, the domain name can be resolved before the resource is requested, reducing request latency and improving loading performance.
+
+See [Using dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch) for more details.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.dnsPrefetch](https://v2.rsbuild.dev/config/performance/dns-prefetch).
+:::

package/docs/configure/app/performance/preconnect.md

@@ -0,0 +1,16 @@
+# performance.preconnect
+
+- **Type:** `undefined | Array<string | PreconnectOption>`
+
+```ts
+interface PreconnectOption {
+  href: string;
+  crossorigin?: boolean;
+}
+```
+
+- **Default:** `undefined`
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.preconnect](https://v2.rsbuild.dev/config/performance/preconnect).
+:::

package/docs/configure/app/performance/prefetch.md

@@ -0,0 +1,21 @@
+# performance.prefetch
+
+- **Type:** `undefined | true | PrefetchOption`
+
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PrefetchOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **Default:** `undefined`
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.prefetch](https://v2.rsbuild.dev/config/performance/prefetch).
+:::

package/docs/configure/app/performance/preload.md

@@ -0,0 +1,23 @@
+# performance.preload
+
+- **Type：** `undefined | true | PreloadOption`
+
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PreloadOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **Default：** `undefined`
+
+Inject the [`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preload) tags for the static assets generated by Rsbuild.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.preload](https://v2.rsbuild.dev/config/performance/preload).
+:::

package/docs/configure/app/performance/print-file-size.md

@@ -0,0 +1,40 @@
+# performance.printFileSize
+
+- **Type:**
+
+```ts
+type PrintFileSizeOptions =
+  | {
+      /**
+       * whether to print total size
+       */
+      total?: boolean;
+      /**
+       * whether to print size of each file
+       */
+      detail?: boolean;
+      /**
+       * whether to print gzip-compressed size
+       */
+      compressed?: boolean;
+    }
+  | boolean;
+```
+
+- **Default:** `true`
+
+Whether to print the file sizes after production build.
+
+```bash
+info    Production file sizes:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
+  dist/html/main/index.html                 5.8 kB       2.5 kB
+  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
+  dist/static/css/main.03221f72.css         1.4 kB       741 B
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.printFileSize](https://v2.rsbuild.dev/config/performance/print-file-size).
+:::

package/docs/configure/app/performance/profile.md

@@ -0,0 +1,10 @@
+# performance.profile
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether capture timing information for each module, same as the [profile](https://rspack.rs/config/other-options#profile) config of Rspack.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.profile](https://v2.rsbuild.dev/config/performance/profile).
+:::

package/docs/configure/app/performance/remove-console.md

@@ -0,0 +1,10 @@
+# performance.removeConsole
+
+- **Type:** `boolean | ConsoleType[]`
+- **Default:** `false`
+
+Whether to remove `console.[methodName]` in production build.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.removeConsole](https://v2.rsbuild.dev/config/performance/remove-console).
+:::

package/docs/configure/app/performance/remove-moment-locale.md

@@ -0,0 +1,10 @@
+# performance.removeMomentLocale
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to remove the locales of [moment.js](https://momentjs.com/).
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - performance.removeMomentLocale](https://v2.rsbuild.dev/config/performance/remove-moment-locale).
+:::

package/docs/configure/app/plugins.md

@@ -0,0 +1,59 @@
+# plugins
+
+- **Type:** `CliPlugin[]`
+- **Default:** `[]`
+
+Used to configure custom Modern.js framework CLI plugins. For information on how to create custom CLI plugins, please refer to [How to Write CLI Plugins](/plugin/introduction.md#cli-plugins).
+
+## Note
+
+This option is **specifically for configuring framework CLI plugins**. If you need to configure other types of plugins, use the appropriate configuration method:
+
+- Use [builderPlugins](/configure/app/builder-plugins.md) for Rsbuild plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain.md) for Rspack plugins.
+- Use the [plugins field in runtime config](/configure/app/runtime/plugins.md) for framework Runtime plugins.
+
+## Examples
+
+Below are examples of using CLI plugins:
+
+### Using plugins from npm
+
+To use plugins from the npm registry, first install the plugins and then import them in your configuration:
+
+```ts title="modern.config.ts"
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Using local plugins
+
+To use plugins from your local repository, import them directly using a relative path:
+
+```ts title="modern.config.ts"
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### Plugin configuration
+
+If a plugin provides custom configuration options, pass them as parameters to the plugin function:
+
+```ts title="modern.config.ts"
+import { myPlugin } from 'my-plugin';
+
+export default defineConfig({
+  plugins: [
+    myPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/docs/configure/app/resolve/alias-strategy.md

@@ -0,0 +1,10 @@
+# resolve.aliasStrategy
+
+- **Type:** `'prefer-tsconfig' | 'prefer-alias'`
+- **Default:** `'prefer-tsconfig'`
+
+Set the strategy for path alias resolution, to control the priority relationship between the paths option in `tsconfig.json` and the [resolve.alias](https://v2.rsbuild.rs/config/resolve/alias) option of Rsbuild.
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致。详细信息请参考 [Rsbuild - resolve.aliasStrategy](https://v2.rsbuild.dev/config/resolve/alias-strategy)。
+:::

package/docs/configure/app/resolve/alias.md

@@ -0,0 +1,9 @@
+# resolve.alias
+
+- **Type:** `string[]`
+
+Create aliases for module paths to simplify import paths or redirect module references.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.alias](https://v2.rsbuild.dev/config/resolve/alias).
+:::

package/docs/configure/app/resolve/condition-names.md

@@ -0,0 +1,13 @@
+# resolve.conditionNames
+
+- **Type:** `string[]`
+- **Default:** Same as Rspack's `resolve.conditionNames`
+
+Specifies the condition names used to match entry points in the [exports](https://nodejs.org/api/packages.html#packages_exports) of a package.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.extensions](https://v2.rsbuild.dev/config/resolve/extensions).
+:::
+:::warning
+Do not enable this configuration option for SSR applications, as it will cause SSR rendering to fail.
+:::

package/docs/configure/app/resolve/dedupe.md

@@ -0,0 +1,9 @@
+# resolve.dedupe
+
+- **Type:** `string[]`
+
+Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size. same as the [resolve.dedupe](https://v2.rsbuild.rs/config/resolve/dedupe) config of Rsbuild.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.dedupe](https://v2.rsbuild.dev/config/resolve/dedupe).
+:::

package/docs/configure/app/resolve/extensions.md

@@ -0,0 +1,13 @@
+# resolve.extensions
+
+- **Type:** `string[]`
+- **Default:** `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json']`
+
+Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - resolve.extensions](https://v2.rsbuild.dev/config/resolve/extensions).
+:::
+:::warning
+Do not enable this configuration option for SSR applications, as it will cause SSR rendering to fail.
+:::