@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.5.0-ultramodern.99

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

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

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

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

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

@@ -0,0 +1,48 @@
+---
+title: buildCache
+---
+
+# 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.
+
+When persistent Rspack cache is enabled, Modern.js treats `cacheDirectory` as a
+base directory and stores each Rsbuild/Rspack environment in its own child
+directory, such as `client`, `server`, or `workerSSR`. This avoids concurrent
+environment compilers writing to the same filesystem cache root.
+
+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,
+  },
+};
+```
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.buildCache" />

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

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

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

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

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

@@ -0,0 +1,20 @@
+---
+title: preconnect
+---
+
+# performance.preconnect
+
+- **Type:** `undefined | Array<string | PreconnectOption>`
+
+```ts
+interface PreconnectOption {
+  href: string;
+  crossorigin?: boolean;
+}
+```
+
+- **Default:** `undefined`
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.preconnect" />

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,14 @@
+---
+title: removeConsole
+---
+
+# performance.removeConsole
+
+- **Type:** `boolean | ConsoleType[]`
+- **Default:** `false`
+
+Whether to remove `console.[methodName]` in production build.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.removeConsole" />

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

@@ -0,0 +1,14 @@
+---
+title: removeMomentLocale
+---
+
+# performance.removeMomentLocale
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to remove the locales of [moment.js](https://momentjs.com/).
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.removeMomentLocale" />

package/docs/configure/app/performance/rsdoctor.mdx

@@ -0,0 +1,42 @@
+---
+title: rsdoctor
+---
+
+# performance.rsdoctor
+
+- **Type:**
+
+```ts
+type RsdoctorConfig =
+  | boolean
+  | {
+      enabled?: boolean;
+      disableClientServer?: boolean;
+    };
+```
+
+- **Default:** `undefined`, Rsdoctor is disabled unless this option is configured.
+
+Configure Rsdoctor diagnostics in Modern.js build. Set this option to `true` to enable Rsdoctor:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: true,
+  },
+});
+```
+
+You can also use object form. When an object is provided, Rsdoctor is enabled unless `enabled` is set to `false`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: {
+      enabled: true,
+    },
+  },
+});
+```
+
+To disable Rsdoctor after enabling it in shared config, set `rsdoctor` to `false` or set `enabled` to `false`.

package/docs/configure/app/plugins.mdx

@@ -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.html#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) for Rsbuild plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) for Rspack plugins.
+- Use the [plugins field in runtime config](/configure/app/runtime/plugins) 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.mdx

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

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

@@ -0,0 +1,13 @@
+---
+title: alias
+---
+
+# resolve.alias
+
+- **Type:** `string[]`
+
+Create aliases for module paths to simplify import paths or redirect module references.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.alias" />

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

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

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