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

package/docs/configure/app/output/disable-css-module-extension.mdx

@@ -0,0 +1,59 @@
+---
+title: disableCssModuleExtension
+---
+
+# output.disableCssModuleExtension
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to treat all `.css` files in the source directory as CSS Modules.
+
+By default, only the `*.module.css` files are treated as CSS Modules. After enabling this config, all `*.css` style files in the source directory will be regarded as CSS Modules.
+
+`.sass`, `.scss` and `.less` files are also affected by `disableCssModuleExtension`.
+
+:::tip
+We do not recommend enabling this config, because after enabling `disableCssModuleExtension`, CSS Modules files and ordinary CSS files cannot be clearly distinguished, which is not conducive to long-term maintenance.
+:::
+
+### Example
+
+```js
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+### Detailed
+
+The following is a detailed explanation of the CSS Modules rules:
+
+#### disableCssModuleExtension is false (default)
+
+The following files are treated as CSS Modules:
+
+- all `*.module.css` files
+
+The following files are treated as normal CSS:
+
+- all `*.css` files (excluding `.module`)
+- all `*.global.css` files
+
+#### disableCssModuleExtension is true
+
+The following files are treated as CSS Modules:
+
+- `*.css` and `*.module.css` files in the source directory
+- `*.module.css` files under node_modules
+
+The following files are treated as normal CSS:
+
+- all `*.global.css` files
+- `*.css` files under node_modules (without `.module`)
+
+:::tip
+For CSS Modules files inside node_modules, please always use the `*.module.css` suffix.
+:::

package/docs/configure/app/output/disable-inline-runtime-chunk.mdx

@@ -0,0 +1,45 @@
+---
+title: disableInlineRuntimeChunk
+---
+
+# output.disableInlineRuntimeChunk
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Used to control whether to inline the bundler's runtime code into HTML.
+
+:::tip What is runtimeChunk
+Modern.js will generate a `builder-runtime.js` file in the dist directory, which is the runtime code of Rspack.
+
+runtimeChunk is a piece of runtime code, which is provided by Rspack, that contains the necessary module processing logic, such as module loading, module parsing, etc. See [Runtime Chunk](https://rspack.rs/config/optimization#optimizationruntimechunk) for details.
+
+:::
+
+In the production environment, Modern.js will inline the runtimeChunk file into the HTML file by default instead of writing it to the dist directory. This is done to reduce the number of file requests.
+
+### Disable Inlining
+
+If you don't want the runtimeChunk file to be inlined into the HTML file, you can set `disableInlineRuntimeChunk` to `true` and a separate `builder-runtime.js` file will be generated.
+
+```js
+export default {
+  output: {
+    disableInlineRuntimeChunk: true,
+  },
+};
+```
+
+### Merge Into Page Chunk
+
+If you don't want to generate a separate runtimeChunk file, but want the runtimeChunk code to be bundled into the page chunk, you can set the config like this:
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain) {
+      chain.optimization.runtimeChunk(false);
+    },
+  },
+};
+```

package/docs/configure/app/output/disable-svgr.mdx

@@ -0,0 +1,22 @@
+---
+title: disableSvgr
+---
+
+# output.disableSvgr
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to transform SVGs into React components. If true, will treat all .svg files as assets.
+
+By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting `disableSvgr` to true to improve build performance.
+
+Modern.js runs the built-in SVGR transform through Rsbuild's parallel worker mode when SVGR is enabled.
+
+```js
+export default {
+  output: {
+    disableSvgr: true,
+  },
+};
+```

package/docs/configure/app/output/disable-ts-checker.mdx

@@ -0,0 +1,53 @@
+---
+title: disableTsChecker
+---
+
+# output.disableTsChecker
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to disable TypeScript type checker during compilation.
+
+By default, Modern.js will run TypeScript checks through the TS-Go native preview toolchain during the build process. You can use `tsconfig.json` or `tools.tsChecker` config to customize the checking behavior.
+
+### Blocking Compilation
+
+- In development build, type errors will not block the compilation process.
+- In production build, type errors will cause the build to fail to ensure the stability of the production code.
+
+### Example
+
+Disable TypeScript type checker:
+
+```js
+export default {
+  output: {
+    disableTsChecker: true,
+  },
+};
+```
+
+Disable type checker in development:
+
+```js
+export default {
+  output: {
+    disableTsChecker: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+Disable type checker in production:
+
+```js
+export default {
+  output: {
+    disableTsChecker: process.env.NODE_ENV === 'production',
+  },
+};
+```
+
+:::tip
+It is not recommended to disable type checker in production, which will reduce the stability of the production code, please use it with caution.
+:::

package/docs/configure/app/output/dist-path.mdx

@@ -0,0 +1,51 @@
+---
+title: distPath
+---
+
+# output.distPath
+
+
+import CommentTips from '@site-docs/components/output-distpath-warning';
+
+<CommentTips />
+
+- **Type：**
+
+```ts
+type DistPathConfig = {
+  root?: string;
+  html?: string;
+  js?: string;
+  css?: string;
+  svg?: string;
+  font?: string;
+  wasm?: string;
+  image?: string;
+  media?: string;
+  worker?: string;
+  assets?: string;
+};
+```
+
+- **Default：**
+
+```js
+const defaultDistPath = {
+  root: 'dist',
+  css: 'static/css',
+  svg: 'static/svg',
+  font: 'static/font',
+  html: 'html',
+  wasm: 'static/wasm',
+  image: 'static/image',
+  media: 'static/media',
+  js: 'static/js',
+  assets: 'static/assets',
+};
+```
+
+Set the directory of the dist files. Modern.js will output files to the corresponding subdirectory according to the file type.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.distPath" />

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

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

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

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

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

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

@@ -0,0 +1,14 @@
+---
+title: filenameHash
+---
+
+# output.filenameHash
+
+- **Type:** `boolean | string`
+- **Default:** `true`
+
+Whether to add a hash value to the filename after the production build.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.filenameHash" />

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

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

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

@@ -0,0 +1,14 @@
+---
+title: injectStyles
+---
+
+# output.injectStyles
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to inject styles into DOM.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.injectStyles" />

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

@@ -0,0 +1,33 @@
+---
+title: inlineScripts
+---
+
+# 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) to false if this option is turned on.
+:::
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.inlineScripts" />

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

@@ -0,0 +1,33 @@
+---
+title: inlineStyles
+---
+
+# 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) to false if this option is turned on.
+:::
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.inlineStyles" />

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

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

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

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

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

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

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

@@ -0,0 +1,18 @@
+---
+title: polyfill
+---
+
+# output.polyfill
+
+- **Type:** `'entry' | 'usage' | 'ua' | 'off'`
+- **Default:** `'entry'`
+
+Via `output.polyfill` you can configure how the polyfill is injected.
+
+import OutputPolyfillExtend from '@site-docs-en/components/output-polyfill-extend';
+
+<OutputPolyfillExtend />
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.polyfill" />

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

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

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

@@ -0,0 +1,20 @@
+---
+title: splitRouteChunks
+---
+
+# 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,
+  },
+}
+```