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

package/docs/configure/app/output/enable-asset-manifest.md

@@ -0,0 +1,36 @@
+# output.enableAssetManifest
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to generate a manifest file that contains information of all assets.
+
+### Example
+
+Enable asset manifest:
+
+```js
+export default {
+  output: {
+    enableAssetManifest: true,
+  },
+};
+```
+
+After compiler, there will be a `dist/manifest.json` file:
+
+```json
+{
+  "files": {
+    "main.css": "/static/css/main.45b01211.css",
+    "main.js": "/static/js/main.52fd298f.js",
+    "html/main/index.html": "/html/main/index.html"
+  },
+  "entrypoints": ["static/css/main.45b01211.css", "static/js/main.52fd298f.js"]
+}
+```
+
+If the current project has multiple types of build artifacts, such as including SSR build artifacts, multiple manifest.json files will be generated.
+
+- web artifact: `asset-manifest.json`
+- node artifact: `asset-manifest-node.json`

package/docs/configure/app/output/enable-css-module-tsdeclaration.md

@@ -0,0 +1,28 @@
+# output.enableCssModuleTSDeclaration
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to generate a TypeScript declaration file for CSS modules.
+
+### Example
+
+Enable CSS module TypeScript declaration:
+
+```js
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+After building, there will be a `.d.ts` file for each CSS module file. For example
+
+```ts
+interface CssExports {
+  title: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```

package/docs/configure/app/output/enable-inline-route-manifests.md

@@ -0,0 +1,16 @@
+# output.disableInlineRouteManifests
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+When using convention-based routing, the framework injects routing information into the client for optimization purposes. By default, routing information is injected into the html, but when this is configured to `true`, routing information is injected into a separate JS file.
+
+Example:
+
+```ts
+export default {
+  output: {
+    disableInlineRouteManifests: true,
+  },
+};
+```

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

@@ -0,0 +1,20 @@
+# output.externals
+
+- **Type:**
+
+```ts
+type Externals =
+  | string
+  | object
+  | function
+  | RegExp
+  | Array<string | object | function | RegExp>;
+```
+
+- **Default:** `undefined`
+
+At build time, prevent some `import` dependencies from being packed into bundles in your code, and instead fetch them externally 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.externals](https://v2.rsbuild.dev/config/output/externals).
+:::

package/docs/configure/app/output/filename-hash.md

@@ -0,0 +1,10 @@
+# output.filenameHash
+
+- **Type:** `boolean | string`
+- **Default:** `true`
+
+Whether to add a hash value to the filename after the production build.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.filenameHash](https://v2.rsbuild.dev/config/output/filename-hash).
+:::

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

@@ -0,0 +1,55 @@
+# output.filename
+
+:::warning
+
+In Modern.js `dev` command or use Modern.js server deployment, don't modify the html output filename. This will cause the page to be 404.
+
+:::
+
+- **Type:**
+
+```ts
+type FilenameConfig = {
+  js?:
+    | string
+    | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
+  css?: string;
+  svg?: string;
+  font?: string;
+  image?: string;
+  media?: string;
+  assets?: string;
+};
+```
+
+- **Default:**
+
+```js
+// Development mode
+const devDefaultFilename = {
+  js: '[name].js',
+  css: '[name].css',
+  svg: '[name].[contenthash:8].svg',
+  font: '[name].[contenthash:8][ext]',
+  image: '[name].[contenthash:8][ext]',
+  media: '[name].[contenthash:8][ext]',
+  assets: '[name].[contenthash:8][ext]',
+};
+
+// Production mode
+const prodDefaultFilename = {
+  js: output.target === 'node' ? '[name].js' : '[name].[contenthash:8].js',
+  css: '[name].[contenthash:8].css',
+  svg: '[name].[contenthash:8].svg',
+  font: '[name].[contenthash:8][ext]',
+  image: '[name].[contenthash:8][ext]',
+  media: '[name].[contenthash:8][ext]',
+  assets: '[name].[contenthash:8][ext]',
+};
+```
+
+Sets the filename of dist files.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.filename](https://v2.rsbuild.dev/config/output/filename).
+:::

package/docs/configure/app/output/inject-styles.md

@@ -0,0 +1,10 @@
+# output.injectStyles
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to inject styles into DOM.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.injectStyles](https://v2.rsbuild.dev/config/output/inject-styles).
+:::

package/docs/configure/app/output/inline-scripts.md

@@ -0,0 +1,29 @@
+# output.inlineScripts
+
+- **Type:**
+
+```ts
+type InlineScriptsTest =
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+
+type InlineScripts =
+  | boolean
+  | InlineScriptsTest
+  | {
+      enable?: boolean | 'auto';
+      test: InlineScriptsTest;
+    };
+```
+
+- **Default:** `/builder-runtime([.].+)?\.js$/`
+
+Whether to inline output scripts files (.js files) into HTML with `<script>` tags.
+
+:::tip
+When using convention-based routing, you need to set [output.splitRouteChunks](/configure/app/output/split-route-chunks.md) to false if this option is turned on.
+:::
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.inlineScripts](https://v2.rsbuild.dev/config/output/inline-scripts).
+:::

package/docs/configure/app/output/inline-styles.md

@@ -0,0 +1,29 @@
+# output.inlineStyles
+
+- **Type:**
+
+```ts
+type InlineStylesTest =
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+
+type InlineStyles =
+  | boolean
+  | InlineStylesTest
+  | {
+      enable?: boolean | 'auto';
+      test: InlineStylesTest;
+    };
+```
+
+- **Default:** `false`
+
+Whether to inline output style files (.css files) into HTML with `<style>` tags.
+
+:::tip
+When using convention-based routing, you need to set [output.splitRouteChunks](/configure/app/output/split-route-chunks.md) to false if this option is turned on.
+:::
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.inlineStyles](https://v2.rsbuild.dev/config/output/inline-styles).
+:::

package/docs/configure/app/output/legal-comments.md

@@ -0,0 +1,18 @@
+# output.legalComments
+
+- **Type:** `'linked' | 'inline' | 'none'`
+- **Default:** `'linked'`
+
+Configure how to handle the legal comment.
+
+A "legal comment" is considered to be any statement-level comment in JS or rule-level comment in CSS that contains `@license` or `@preserve` or that starts with `//!` or `/*!`. These comments are preserved in output files by default since that follows the intent of the original authors of the code.
+
+This behavior can be configured by using one of the following options:
+
+- `linked`: Extract all legal comments to a .LEGAL.txt file and link to them with a comment.
+- `inline`: Preserve all legal comments in original position.
+- `none`: Remove all legal comments.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.legalComments](https://v2.rsbuild.dev/config/output/legal-comments).
+:::

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

@@ -0,0 +1,22 @@
+# output.minify
+
+- **Type:**
+
+```ts
+type Minify =
+  | boolean
+  | {
+      js?: boolean;
+      jsOptions?: SwcJsMinimizerRspackPluginOptions;
+      css?: boolean;
+      cssOptions?: LightningCssMinimizerRspackPluginOptions;
+    };
+```
+
+- **Default:** `true`
+
+Configure whether to enable code minification in production mode, or to configure minimizer options.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.minify](https://v2.rsbuild.dev/config/output/minify).
+:::

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,44 @@
+# 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,
+  },
+};
+```
+
+:::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).
+:::