@modern-js/main-doc 2.41.0 → 2.42.1

package/docs/en/apis/app/commands.mdx

@@ -276,7 +276,9 @@ Normally, only the part of the code modified by this commit needs to be checked
 Usage: modern test [options]
 
 Options:
-  -h, --help  show command help
+  -u --updateSnapshot  use this flag to re-record snapshots.
+  --watch              watch files for changes and rerun tests related to changed files.
+  -h, --help           show command help
 ```
 
 :::tip

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

@@ -1,10 +1,20 @@
 ---
-sidebar_label: enableInlineRouteManifests
+sidebar_label: disableInlineRouteManifests
 ---
 
-# output.enableInlineRouteManifests
+# output.disableInlineRouteManifests
 
 - **Type:** `boolean`
-- **Default:** `true`
+- **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 `false`, routing information is injected into a separate JS file.
+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/en/configure/app/tools/bundler-chain.mdx

@@ -4,10 +4,6 @@ sidebar_label: bundlerChain
 
 # tools.bundlerChain
 
-:::tip
-This config is provided by Modern.js Builder, more detail can see [tools.bundlerChain](https://modernjs.dev/builder/en/api/config-tools.html#toolsbundlerchain).
-:::
-
 import Main from '@modern-js/builder-doc/docs/en/config/tools/bundlerChain.mdx';
 
 <Main />

package/docs/en/guides/advanced-features/build-performance.mdx

@@ -0,0 +1,156 @@
+---
+sidebar_position: 12
+---
+
+# Improve Build Performance
+
+Modern.js optimizes build performance by default, but as the project becomes larger, you may encounter some build performance problems.
+
+This document provides some optional speed-up strategies, developers can choose some of them to improve the build performance.
+
+:::tip 📢 Notice
+The strategies in [Bundle Size Optimization](/guides/advanced-features/optimize-bundle.html) can also be used to improve build performance, so we won't repeat them here.
+:::
+
+## General optimization strategy
+
+The following are some general optimization strategies, which can speed up the development build and production build, and some of them also optimize the bundle size.
+
+### Upgrade Node.js version
+
+In general, updating Node.js to the latest [LTS release](https://github.com/nodejs/release#release-schedule) will help improve build performance.
+
+Especially for devices with Apple M1/M2 chips, it is recommended to use Node 18.
+
+Node >= 16 provides Apple Silicon binaries by default, so the performance on M1/M2 models will be greatly improved than Node 14. According to our tests, **After switching from Node 14 to Node >= 16, the compilation speed can be improved by more than 100%**.
+
+You can switch to Node 18 by following steps:
+
+```bash
+# Install Node v18
+nvm install 18
+
+# switch to Node 18
+nvm use 18
+
+# Set Node 18 as the default version
+nvm default 18
+
+# View Node version
+node -v
+```
+
+### Using Rspack build
+
+If you have higher build performance requirements, you can easily switch to Rspack build mode, see [Using Rspack](/guides/advanced-features/rspack-start.html) for more information.
+
+### Using SWC or esbuild
+
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+[esbuild](https://esbuild.github.io/) is a front-end build tool based on Golang. It has the functions of bundling, compiling and minimizing JavaScript code. Compared with traditional tools, the performance is significantly improved. When minimizing code, compared to webpack's built-in terser minimizer, esbuild has dozens of times better performance.
+
+Modern.js provides SWC plugin and esbuild plugin that allow you to use SWC or esbuild instead of babel-loader, ts-loader and terser for transformation and minification process. See:
+
+- [SWC plugin document](/configure/app/tools/swc.html)
+- [esbuild plugin document](/configure/app/tools/esbuild.html)
+
+:::tip SWC vs esbuild
+The SWC compiled outputs has better compatibility, supports polyfills such as core-js, and has more complete features, so it is recommended to use the SWC plugin first.
+:::
+
+### Avoid using ts-loader
+
+By default, Modern.js uses Babel to compile TS files. After enabling the [tools.tsLoader](/en/configure/app/tools/ts-loader.html) option, `ts-loader` will be used to compile TS files.
+
+Please avoid using `ts-loader` because it requires additional parsing and type checking, which will slow down the build.
+
+```js
+export default {
+  tools: {
+    // remove this config
+    tsLoader: {},
+  },
+};
+```
+
+See the [tools.tsLoader documentation](/en/configure/app/tools/ts-loader.html) for details.
+
+## Development optimization strategies
+
+The following are strategies for improve build performance in development environment.
+
+### Adjust Source Map format
+
+In order to provide a good debugging experience, Modern.js uses the `cheap-module-source-map` format Source Map by default in the development environment, which is a high-quality Source Map format and will bring certain performance overhead.
+
+You can improve build speed by adjusting the source map format of your development environment.
+
+For example to disable Source Map:
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool(false);
+      }
+    },
+  },
+};
+```
+
+Or set the source map format of the development environment to the cheapest `eval` format:
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool('eval');
+      }
+    },
+  },
+};
+```
+
+> For detailed differences between different Source Map formats, see [webpack - devtool](https://webpack.js.org/configuration/devtool/).
+
+### Adjust Browserslist for development
+
+This strategy is similar to ["Adjust Browserslist"](/guides/advanced-features/optimize-bundle.html#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead in the development environment.
+
+For example, you can add the following config to `package.json`, which means that only the latest browsers are compatible in the development environment, and the actual browsers are compatible in the production environment:
+
+```json
+{
+  "browserslist": {
+    "production": [">0.2%", "not dead", "not op_mini all"],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
+```
+
+Note that this strategy can lead to some differences in the build result of development production environment.
+
+## Production optimization strategies
+
+The following are strategies for improve build performance in production environment.
+
+### Disable Source Map
+
+If your project does not need Source Map in the production, you can turn it off through the `disableSourceMap` config to improve the build speed.
+
+```js
+export default {
+  output: {
+    disableSourceMap: true,
+  },
+};
+```
+
+See [output.disableSourceMap](/en/configure/app/output/disable-source-map.html) for details.

package/docs/en/guides/advanced-features/optimize-bundle.mdx

@@ -0,0 +1,115 @@
+---
+sidebar_position: 13
+---
+
+# Bundle Size Optimization
+
+Bundle size optimization is an important part in production environment because it directly affects the user experience of online users. In this document, we will introduce some common bundle size optimization methods in Builder.
+
+## Reduce duplicate dependencies
+
+In real projects, there will be some third-party dependencies installed with multiple versions. Duplicate dependencies can lead to larger bundles and slower builds.
+
+We can detect or eliminate duplicate dependencies with some community tools.
+
+- If you are using `pnpm >= 7.26.0`, you can use the [pnpm dedupe](https://pnpm.io/cli/dedupe) command to upgrade and eliminate duplicate dependencies.
+
+```bash
+pnpm dedupe
+```
+
+- If you are using `pnpm < 7.26.0`, you can use [pnpm-deduplicate](https://github.com/ocavue/pnpm-deduplicate) to analyze all duplicate dependencies, then update dependencies or declare [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides) to merge duplicated dependencies.
+
+```bash
+npx pnpm-deduplicate --list
+```
+
+- If you are using `yarn`, you can use [yarn-deduplicate](https://github.com/scinos/yarn-deduplicate) to automatically merge duplicated dependencies:
+
+```bash
+npx yarn-deduplicate && yarn
+```
+
+## Use lightweight libraries
+
+It is recommended to using lightweight libraries in your project, such as replacing [moment](https://momentjs.com/) with [day.js](https://day.js.org/).
+
+If you want to find out the large libraries in the project, you can add the `BUNDLE_ANALYZE=true` environment variable when building:
+
+```bash
+BUNDLE_ANALYZE=true pnpm build
+```
+
+See the [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.html) configuration for details.
+
+## Adjust Browserslist
+
+The Builder will compile the code according to the project's Browserslist config, and inject some Polyfills. If the project does not need to be compatible with legacy browsers, you can adjust the Browserslist and drop some legacy browsers, thereby reducing the compilation overhead on syntax and polyfill.
+
+Builder's default Browserslist config is:
+
+```js
+['> 0.01%', 'not dead', 'not op_mini all'];
+```
+
+For example, if you only need to be compatible with browsers above Chrome 61, you can change it to:
+
+```js
+['Chrome >= 61'];
+```
+
+:::tip
+Please read the [Browserslist](https://modernjs.dev/builder/en/guide/advanced/browserslist.html) chapter to know more about the usage of Browserslist.
+:::
+
+## Usage polyfill
+
+When it is clear that third-party dependencies do not require additional polyfill, you can set [output.polyfill](/configure/app/output/polyfill.html) to `usage`.
+
+In `usage` mode, Builder analyzes the syntax used in the source code and injects the required polyfill code on demand to reduce the size of polyfill.
+
+```js
+export default {
+  output: {
+    polyfill: 'usage',
+  },
+};
+```
+
+:::tip
+Please read the [Browser Compatibility](https://modernjs.dev/builder/en/guide/advanced/browser-compatibility.html) chapter to know more about the usage of Browserslist.
+:::
+
+## Image Compression
+
+In general front-end projects, the size of image often accounts for a large proportion of the total bundle size of the project.So if the image size can be reduced as much as possible, it will have a significant optimization effect on the project bundle size. You can enable image compression by registering a plugin in the Builder:
+
+```js
+import { builderPluginImageCompress } from '@modern-js/builder-plugin-image-compress';
+
+// Add the plugin to the Builder
+builder.addPlugins([builderPluginImageCompress()]);
+```
+
+See details in [plugin-image-compress](https://modernjs.dev/builder/en/plugins/plugin-image-compress.html).
+
+## Split Chunk
+
+A great chunk splitting strategy is very important to improve the loading performance of the application. It can make full use of the browser's caching mechanism to reduce the number of requests and improve the loading speed of the application.
+
+A variety of [chunk splitting strategies](https://modernjs.dev/builder/en/guide/optimization/split-chunk) are built into Builder, which can meet the needs of most applications. You can also customize the chunk splitting config according to your own business scenarios.
+
+For example, split the `axios` library under node_modules into `axios.js`:
+
+```js
+export default {
+  performance: {
+    chunkSplit: {
+      strategy: 'split-by-experience',
+      forceSplitting: {
+        axios: /node_modules\/axios/,
+      },
+    },
+  },
+};
+```

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -83,7 +83,7 @@ For example, if you are using pnpm, you can update the Rspack version with `over
   "pnpm": {
     "overrides": {
       "@rspack/core": "nightly",
-      "@rspack/dev-client": "nightly",
+      "@rspack/plugin-react-refresh": "nightly",
       "@rspack/plugin-html": "nightly"
     }
   }

package/docs/en/guides/advanced-features/source-build.mdx

@@ -0,0 +1,161 @@
+---
+sidebar_position: 11
+---
+
+# Source Code Build Mode
+
+The source code build mode is used in the monorepo development scenario, allowing developers to directly reference the source code of other sub-projects within the monorepo for development.
+
+## Use Cases
+
+In a monorepo, there are two main ways for projects to reference each other: artifact referencing and source code referencing. Let's use a simple monorepo as an example to illustrate the use case of source code referencing.
+
+For example, the monorepo contains an app application and a lib:
+
+```ts
+monorepo
+├── app
+└── lib
+    └── src
+        └── index.ts
+```
+
+The app is built using Modern.js and relies on some methods from the lib:
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib": "workspace:*"
+  }
+}
+```
+
+### Artifact Referencing
+
+**When using artifact referencing, the current project references the artifacts built from other sub-projects.**
+
+In the example above, the lib is written in TypeScript. Typically, we need to build the lib's code in advance to generate JavaScript artifacts so that the app can reference it correctly. When the lib's code is updated, we need to rebuild it (or use `tsc --watch`) to ensure that the app can use the latest code.
+
+The advantages of this approach are:
+
+- The build processes of each sub-project are completely independent and can have different build configurations.
+- Build caching can be applied to individual sub-projects.
+
+The disadvantages are:
+
+- The HMR chain becomes longer during local development.
+- The process becomes cumbersome when a project contains multiple lib packages.
+
+### Source Code Referencing
+
+**When using source code referencing, the current project references the source code of other sub-projects for building.**
+
+In the example mentioned earlier, when you enable the source code build mode and add the relevant configuration in the `lib` directory, Modern.js will automatically reference the `src/index.ts` source code of the lib. This means that you don't need to build the lib's code in advance, and when the source code of the lib is updated, it can trigger automatic hot updates for the app.
+
+The advantages of this approach are:
+
+- The sub-project does not rely on a build tool and does not require build configurations. The code of the sub-project will be compiled by the build tool of the current project.
+- There is no need to execute the build process for the sub-projects in advance.
+- HMR is more efficient during local development.
+
+The disadvantages are:
+
+- The current project needs to support syntax features used by sub-projects and follow the same syntax specifications, such as using a consistent version of decorator syntax. If the current project and sub-projects require different build configurations, building from source code may not be suitable.
+- The current project requires compiling more code, which may result in longer build times.
+
+## Building from Source Code
+
+### Enabling Configuration
+
+You can enable source code build mode by setting [experiments.sourceBuild](/configure/app/experiments/source-build.html) to `true`.
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+### Configuring Sub-projects
+
+When the source code build mode is enabled, the Modern.js will prioritize reading the file specified in the `source` field of the sub-project during the build process. Therefore, you need to configure the `source` field in the package.json file of the sub-project and point it to the source code file.
+
+For example, in the following example, when the lib package is referenced, the `./src/index.ts` file will be read for building:
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+If the sub-project uses [exports](https://nodejs.org/api/packages.html#package-entry-points) field, you also need to add the `source` field in the `exports` field.
+
+```json title="package.json"
+{
+  "name": "lib",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## Configure Project Reference
+
+In a TypeScript project, you need to use the capability provided by TypeScript called [Project Reference](https://www.typescriptlang.org/docs/handbook/project-references.html). It helps you develop source code more effectively.
+
+### Introduction
+
+Project reference provides the following capabilities:
+
+- It allows TypeScript to correctly recognize the types of other sub-projects without the need to build them.
+- When you navigate the code in VS Code, it automatically takes you to the corresponding source code file of the module.
+- Modern.js reads the project reference configuration and automatically recognizes the `tsconfig.compilerOptions.path` configuration of the sub-project, so that the use of aliases in the sub-project works correctly.
+
+### Example
+
+In the example mentioned earlier, since the app project references the lib sub-project, we need to configure the `composite` and `references` options in the app project's `tsconfig.json` file and point them to the corresponding relative directory of lib:
+
+```json title="app/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
+}
+```
+
+After adding these two options, the project reference is already configured. You can restart VS Code to see the effects of the configuration.
+
+Note that the above example is a simplified one. In real monorepo projects, there may be more complex dependency relationships. You need to add a complete `references` configuration for the functionality to work correctly.
+
+:::tip
+If you want to learn more about project reference, please refer to the official documentation on [TypeScript - Project References](https://www.typescriptlang.org/docs/handbook/project-references.html).
+:::
+
+## Caveat
+
+When using source code build mode, there are a few things to keep in mind:
+
+1. Ensure that the current project can compile the syntax or features used in the sub-project. For example, if the sub-project uses Stylus to write CSS, the current app needs to support Stylus compilation.
+2. Ensure that the current project has the same code syntax and features as the sub-project, such as consistent syntax versions for decorators.
+3. Source code building may have some limitations. When encountering issues, you can remove the `source` field from the sub-project's package.json and debug using the built artifacts of the sub-project.
+4. When `composite: true` is enabled, TypeScript will generate `*.tsbuildinfo` temporary files. You need to add these temporary files to the `.gitignore` file.
+
+```text title=".gitignore"
+*.tsbuildinfo
+```

package/docs/en/guides/advanced-features/testing.mdx

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 11
+sidebar_position: 14
 ---
 
 # Using Jest
 
 Modern.js integrates the testing capabilities of [Jest](https://jestjs.io/) by default.
 
-First need to execute `pnpm run new` to enable [unit test/integration test] features:
+First need to execute `pnpm run new` to enable "unit test/integration test" features:
 
 ```bash
 ? Please select the operation you want: Enable features

package/docs/en/guides/advanced-features/using-storybook.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 12
+sidebar_position: 15
 ---
 
 # Using StorybookV6

package/docs/en/guides/advanced-features/web-server.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 13
+sidebar_position: 16
 ---
 
 # Custom Web Server

package/docs/en/guides/get-started/tech-stack.mdx

@@ -14,7 +14,7 @@ In this document, you can learn about the main technology stack involved in the
 
 Modern.js uses [React 18](https://react.dev/) to build user interfaces and is also compatible with React 17.
 
-The underlying Builder of Modern.js also supports building Vue applications. If you need to use Vue, you can refer to ["Building Vue App"](https://modernjs.dev/builder/en/guide/framework/vue3.html).
+Rsbuild supports building Vue applications. If you need to use Vue, you can refer to ["Rsbuild - Vue"](https://rsbuild.dev/guide/framework/vue3).
 
 ---