@modern-js/main-doc 2.11.0 → 2.13.0

package/docs/en/configure/app/usage.mdx

@@ -19,17 +19,33 @@ Server runtime configuration can be configured in the `modern.server-runtime.con
 
 ## Configure in the configuration file
 
-Modern.js configuration files are defined in the root path of the project, and supports `.js`, `.ts` and `.mjs` formats:
+Modern.js configuration files are defined in the root path of the project, and supports `.ts`, `.js` and `.mjs` formats:
 
-- `modern.config.js`
 - `modern.config.ts`
+- `modern.config.js`
 - `modern.config.mjs`
 
-### modern.config.js
+### modern.config.ts (recommended)
 
-You can use JavaScript syntax in the `modern.config.js` file and it is more flexible than in the `package.json` file.
+We recommend using configuration files in `.ts` format, which provides friendly TypeScript type hints to help you avoid configuration errors.
 
-For example, you can define configuration options for function types in `modern.config.js`:
+Import the `defineConfig` tool function from `@modern-js/app-tools`, which will help you with configuration type derivation and type completion:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
+
+### modern.config.js
+
+If you are developing a non-TypeScript project, you can use the configuration file in .js format:
 
 ```js title="modern.config.js"
 export default {
@@ -51,24 +67,6 @@ export default {
 };
 ```
 
-### modern.config.ts (recommended)
-
-We recommend using configuration files in `.ts` format, which provides friendly TypeScript type hints to help you avoid configuration errors.
-
-Import the `defineConfig` tool function from `@modern-js/app-tools`, which will help you with configuration type derivation and type completion:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  source: {
-    alias: {
-      '@common': './src/common',
-    },
-  },
-});
-```
-
 ### Export Configuration Function
 
 Modern.js supports exporting a function in the configuration file, and you can dynamically compute the configuration in the function and return it to Modern.js.
@@ -200,3 +198,47 @@ modern.config.local.ts
 modern.config.local.js
 modern.config.local.mjs
 ```
+
+## Merge Multiple Configurations
+
+In some cases, you may need to merge multiple configurations into one configuration. You can use the `mergeConfig` util to merge multiple configurations.
+
+The `mergeConfig` function accepts an array as a parameter, and each item in the array is a configuration object. `mergeConfig` will deeply merge each configuration object in the array, automatically merge multiple functions into an array, and returns a merged configuration object.
+
+### Example
+
+```ts title="modern.config.ts"
+import { mergeConfig } from '@modern-js/app-tools';
+
+const config1 = {
+   dev: {
+     port: 3000,
+   },
+   tools: {
+     postcss: () => console. log('config1');
+   },
+};
+const config2 = {
+   dev: {
+     port: 3001,
+   },
+   tools: {
+     postcss: () => console. log('config2');
+   },
+};
+
+const mergedConfig = mergeConfig([config1, config2]);
+```
+
+In the above example, the merged configuration object is:
+
+```ts
+const mergedConfig = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: [() => console.log('config1'), () => console.log('config2')],
+  },
+};
+```

package/docs/en/guides/advanced-features/bff/function.mdx

@@ -114,7 +114,7 @@ For example, following the example, a `GET` interface can be exported.
 export const get = async () => {
   return {
     name: 'Modern.js',
-    desc: '现代 web 工程方案',
+    desc: 'Web engineering system',
   };
 };
 ```
@@ -125,14 +125,14 @@ Following the example below, a `POST` interface can be exported.
 export const post = async () => {
   return {
     name: 'Modern.js',
-    desc: '现代 web 工程方案',
+    desc: 'Web engineering system',
   };
 };
 ```
 
 - Modern.js supports 9 definitions for HTTP Method: `GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`, can be exported using these methods as functions.
 
-- The name is size insensitive，if `GET`，can write `get`、`Get`、`GEt`、`GET`，can be accurately identified. But default export as `export default xxx` will be map to `Get`.
+- The name is size insensitive, if `GET`, can write `get`、`Get`、`GEt`、`GET`, can be accurately identified. But default export as `export default xxx` will be map to `Get`.
 
 - Multiple functions of different Methods can be defined in one file, but if multiple functions of the same Method are defined, only the first will take effect.
 

package/docs/en/guides/advanced-features/code-split.mdx

@@ -17,7 +17,7 @@ When you use Modern.js [Conventional routing](/guides/basic-features/routes#conv
 
 ## import
 
-use dynamic `import()`，`import` The JS modules pass to this API will be packaged into a separate JS file as a new packaging entry, for example:
+use dynamic `import()`, `import` The JS modules pass to this API will be packaged into a separate JS file as a new packaging entry, for example:
 
 ```ts
 import('./math').then(math => {
@@ -60,7 +60,7 @@ For detail, see [React lazy](https://reactjs.org/docs/code-splitting.html#reactl
 
 ## loadable
 
-use `loadable` API，for example:
+use `loadable` API, for example:
 
 ```ts
 import loadable from '@modern-js/runtime/loadable';

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

@@ -4,7 +4,7 @@ sidebar_position: 8
 ---
 # ESLint
 
-**Modern.js ESLint Rules** is the full set of **ESLint** rules，includes `@modern-js` (Lint rules for Node.js projects) and `@modern-js-app` (Lint rules for web projects).
+**Modern.js ESLint Rules** is the full set of **ESLint** rules, includes `@modern-js` (Lint rules for Node.js projects) and `@modern-js-app` (Lint rules for web projects).
 
 More ESLint usage is described below with specific questions.
 

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

@@ -13,7 +13,7 @@ First need to execute `pnpm run new` to enable the SSG features:
 ? Enable features Enable SSG
 ```
 
-After execute script，register SSG plugin in `modern.config.ts`:
+After execute script, register SSG plugin in `modern.config.ts`:
 
 ```ts title="modern.config.ts"
 import ssgPlugin from '@modern-js/plugin-ssg';
@@ -106,7 +106,7 @@ export default defineConfig({
 });
 ```
 
-run `pnpm run build` and `pnpm run serve`，access `http://localhost:8080/about`. In the Preview view, you can see that the page has been rendered.
+run `pnpm run build` and `pnpm run serve`, access `http://localhost:8080/about`. In the Preview view, you can see that the page has been rendered.
 
 Looking at the bundle file, a new `main/about/index.html` file has been added in the `dist/` directory.
 

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

@@ -246,6 +246,21 @@ if (process.env.MODERN_TARGET === 'browser') {
 }
 ```
 
+After packaging in the development environment, SSR and CSR artifacts will be compiled into the following content. Therefore, there will be no more errors due to Web API in the SSR environment:
+
+```ts
+// SSR production
+if (false) {
+}
+
+// CSR production
+if (true) {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
 :::note
 For more information, see [environment variables](/guides/basic-features/env-vars).
 
@@ -253,7 +268,9 @@ For more information, see [environment variables](/guides/basic-features/env-var
 
 ### Use File Suffix
 
-In the second case, the Treeshaking method does not guarantee that the code is completely separated. Modern.js also supports the packaging file of SSR Bundle and CSR Bundle products through the file suffixed with `.node.`.
+However, in the second case, for example, when `fs-extra` is imported into the code, it internally uses the Node API with side effects. If it is directly referenced in the component, it will cause CSR loading errors.
+
+Env vars is not effective in this situation. Modern.js also supports distinguishing SSR Bundle and CSR Bundle packaging files through files with the `.node.` suffix.
 
 For example, the import of `fs-extra` in the code, when it is directly referenced to the component, will cause the CSR to load an error. You can create `.ts` and `.node.ts` files of the same name as a layer of proxy:
 
@@ -280,7 +297,27 @@ export const loader = () => {
 
 ### Independent File
 
-Both of the above methods will bring some burden to the developer. Modern.js based on [Nested Routing](/guides/basic-features/routes) developed and designed [Data Fetch](/guides/basic-features/data-fetch) to separate CSR and SSR code.
+Both of the above methods can bring some mental burden to developers. In real business scenarios, we found that most of the mixed Node/Web code occurs in data requests.
+
+Therefore, Modern.js developed a [Data Fetch](/guides/basic-features/data-fetch) to separate CSR and SSR code based on [Nested Routing](/guides/basic-features/routes).
+
+We can separate **data request** and **component code** by using independent files. Write component logic in `routes/page.tsx` and data request logic in `routes/page.loader.ts`.
+
+```ts title="routes/page.tsx"
+export default Page = () => {
+  return <div>Hello World<div>
+}
+```
+
+```ts title="routes/page.loader.tsx"
+import fse from 'fs-extra';
+export default () => {
+  const file = fse.readFileSync('./myfile');
+  return {
+    ...
+  };
+}
+```
 
 ## Remote Request
 
@@ -317,7 +354,7 @@ The streaming SSR of Modern.js is implemented based on React Router, and the mai
 
 ### Return async data
 
-```ts title='page.loader.ts'
+```ts title="page.loader.ts"
 import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
 
 interface User {
@@ -351,7 +388,7 @@ therefore, the parameter passed to `defer` is `{data: user}`.
 
 `defer` can also receive asynchronous data and synchronous data at the same time. For example:
 
-```ts title='page.loader.ts'
+```ts title="page.loader.ts"
 
 // skip some codes
 
@@ -388,7 +425,7 @@ export default ({ params }: LoaderFunctionArgs) => {
 
 Use the `Await` component to render the data returned asynchronously from the Data Loader. For example:
 
-```tsx title='page.tsx'
+```tsx title="page.tsx"
 import { Await, useLoaderData } from '@modern-js/runtime/router';
 import { Suspense } from 'react';
 import type { Data } from './page.loader';
@@ -430,7 +467,7 @@ So, here we import like this: `import type { Data } from './page.loader'`;
 
 You can also get the asynchronous data returned by Data Loader through `useAsyncValue`. For example:
 
-```tsx title='page.tsx'
+```tsx title="page.tsx"
 import { useAsyncValue } from '@modern-js/runtime/router';
 
 // skip some codes
@@ -468,7 +505,7 @@ export default Page;
 The `errorElement` property of the `Await` component can be used to handle errors thrown when the Data Loader executes or when a child component renders.
 For example, we intentionally throw an error in the Data Loader function:
 
-```ts title='page.loader.ts'
+```ts title="page.loader.ts"
 import { defer } from '@modern-js/runtime/router';
 
 export default () => {
@@ -484,7 +521,7 @@ export default () => {
 
 Then use `useAsyncError` to get the error, and assign the component used to render the error to the `errorElement` property of the `Await` component:
 
-```tsx title='page.ts'
+```tsx title="page.ts"
 import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
 import { Suspense } from 'react';
 

package/docs/en/guides/basic-features/alias.mdx

@@ -4,7 +4,7 @@ sidebar_position: 8
 ---
 # Alias
 
-Modern.js allow aliases in JS and CSS，and the following aliases are built in:
+Modern.js allow aliases in JS and CSS, and the following aliases are built in:
 
 ```js
 {

package/docs/en/guides/basic-features/data-fetch.mdx

@@ -223,7 +223,7 @@ Currently, only CSR is supported, so stay tuned for Streaming SSR.
 Add the following code to `user/layout.loader.ts`:
 
 ```ts title="routes/user/layout.loader.ts"
-import { defer } from "@edenx/runtime/router"
+import { defer } from "@modern-js/runtime/router"
 
 const loader = () =>
 defer({

package/docs/en/guides/basic-features/env-vars.mdx

@@ -6,7 +6,7 @@ sidebar_position: 7
 
 Modern.js provides support for environment variables, including built-in environment variables and custom environment variables.
 
-## Built-in Environment
+## Built-in Environment Variables
 
 ### ASSET_PREFIX
 
@@ -31,7 +31,7 @@ MODERN_ENV priority is higher than NODE_ENV.
 
 ### MODERN_TARGET
 
-Auto inject when use `@modern-js/runtime`，Used to distinguish between SSR and CSR environments. Developers can judge by themselves in the code, and dead code will be removed by default when building.
+Auto inject when use `@modern-js/runtime`, Used to distinguish between SSR and CSR environments. Developers can judge by themselves in the code, and dead code will be removed by default when building.
 
 ```ts title="App.tsx"
 function App() {
@@ -93,7 +93,7 @@ The `.env` file follows the following loading rules:
 
 When you need to use different config according to the environment, you can define environment variables in the `.env` file corresponding to the environment name, and manually set the execution environment when starting the project.
 
-For example, when starting a project with the following command，the `.env` and `.env.staging` will load:
+For example, when starting a project with the following command, the `.env` and `.env.staging` will load:
 
 ```shell
 MODERN_ENV=staging pnpm run dev
@@ -129,7 +129,7 @@ In custom HTML templates, you can also use such environment variables directly.
 
 ### Any Other Names
 
-If you need to use environment variables with any other names in your code，you can config [`source.globalVars`](/configure/app/source/global-vars), for example:
+If you need to use environment variables with any other names in your code, you can config [`source.globalVars`](/configure/app/source/global-vars), for example:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -171,4 +171,4 @@ const foo = TWO;
 const foo = 1 + 1;
 ```
 
-In most cases, `source.globalVars` is already sufficient to replace variables. But the values passed in by `source.globalVars` will be serialized by JSON by default. So it cannot be replaced like `1 + 1` in the example above，at this time, we need use [`source.define`](/configure/app/source/define).
+In most cases, `source.globalVars` is already sufficient to replace variables. But the values passed in by `source.globalVars` will be serialized by JSON by default. So it cannot be replaced like `1 + 1` in the example above, at this time, we need use [`source.define`](/configure/app/source/define).

package/docs/en/guides/basic-features/html.mdx

@@ -173,10 +173,6 @@ In the application root directory, create the `config/html/` directory, which su
     <%= meta %>
     <title><%= title %></title>
     <%= topTemplate %>
-
-    <script>
-      window.__assetPrefix__ = '<%= assetPrefix %>';
-    </script>
     <%= headTemplate %>
     {/* webpack inject css  */}
   </head>

package/docs/en/guides/basic-features/routes.mdx

@@ -2,6 +2,7 @@
 title: Routes
 sidebar_position: 1
 ---
+
 # Routes
 
 Modern.js build-in provides partial support for [React Router 6](https://reactrouter.com/en/main) and provides various types of routing modes. According to different [entry](/guides/concept/entries) types, routing is divided into three modes, namely **Conventional routing**, **Self-controlled routing** and **Other**.
@@ -57,8 +58,8 @@ Similarly, `routes/user/layout.tsx` will be used as a layout component for all c
 ```tsx
 <Layout>
   <UserLayout>
-    <UserPage>
-  <UserLayout>
+    <UserPage />
+  </UserLayout>
 </Layout>
 ```
 
@@ -106,8 +107,8 @@ In order to facilitate the introduction of the relationship between `<Layout>` a
 ```tsx
 <Layout>
   <UserLayout>
-    <UserPage>
-  <UserLayout>
+    <UserPage />
+  </UserLayout>
 </Layout>
 ```
 
@@ -158,10 +159,9 @@ The `routes/$.tsx` component is rendered when accessing any path that does not m
 import { useParams } from '@modern-js/runtime/router';
 // When the path is `/aaa/bbb`
 const params = useParams();
-params['*']  // => 'aaa/bbb'
+params['*']; // => 'aaa/bbb'
 ```
 
-
 ### Layout with No Path
 
 When a directory name begins with `__`, the corresponding directory name is not converted to the actual routing path, such as the following file directory:
@@ -230,15 +230,15 @@ When a route jumps from `/` to `/blog`, if the JS Chunk of the `<Blog>` componen
 You can redirect routes by creating a [`data loader`](/guides/basic-features/data-fetch) file, Suppose you have the file `routes/user/page.tsx` and you want to redirect the route corresponding to this file, you can create the file `routes/user/page.loader.ts`:
 
 ```ts title="routes/user/page.loader.ts"
-import { redirect } from "@edenx/runtime/router"
+import { redirect } from '@modern-js/runtime/router';
 
 export default () => {
   const user = await getUser();
-  if(!user){
+  if (!user) {
     return redirect('/login');
   }
   return null;
-}
+};
 ```
 
 ### ErrorBoundary
@@ -255,15 +255,15 @@ Within the `<ErrorBoundary>` component, you can use [useRouteError](/apis/app/ru
 
 ```tsx
 import { useRouteError } from '@modern-js/runtime/router';
-export default const ErrorBoundary = () => {
+export const ErrorBoundary = () => {
   const error = useRouteError();
   return (
     <div>
-        <h1>{error.status}</h1>
-        <h2>{error.message}</h2>
+      <h1>{error.status}</h1>
+      <h2>{error.message}</h2>
     </div>
-  )
-}
+  );
+};
 ```
 
 ### Hooks before rendering
@@ -286,15 +286,13 @@ This feature is useful when the application requires pre-page data, custom data
 :::
 
 ```ts title="src/routes/layout.tsx"
-import {
-  RuntimeContext,
-} from '@modern-js/runtime';
+import { RuntimeContext } from '@modern-js/runtime';
 
 export const init = (context: RuntimeContext) => {
   return {
     message: 'Hello World',
-  }
-}
+  };
+};
 ```
 
 ```tsx title="src/routes/page.tsx"
@@ -305,7 +303,7 @@ export default () => {
   const { message } = context.getInitData();
 
   return <div>{message}</div>;
-}
+};
 ```
 
 When working with SSR, the browser side can get the data returned by `init` during SSR, and the developer can decide whether to retrieve the data on the browser side to overwrite the SSR data, for example:
@@ -317,18 +315,18 @@ export const init = (context: RuntimeContext) => {
   if (process.env.MODERN_TARGET === 'node') {
     return {
       message: 'Hello World By Server',
-    }
+    };
   } else {
     const { context } = runtimeContext;
     const data = context.getInitData();
     // If do not get the expected data
     if (!data.message) {
       return {
-        message: 'Hello World By Client'
-      }
+        message: 'Hello World By Client',
+      };
     }
   }
-}
+};
 ```
 
 ### Runtime Configuration
@@ -341,12 +339,34 @@ import type { AppConfig } from '@modern-js/runtime';
 export const config = (): AppConfig => {
   return {
     router: {
-      supportHtml5History: false
-    }
-  }
+      supportHtml5History: false,
+    },
+  };
 };
 ```
 
+### Prefetch
+
+When using convention-based routing, Modern.js will automatically split chunks according to the route, and when the user accesses a specific route, the corresponding resources will be loaded automatically, which can effectively reduce the first screen loading time. However, this also brings a problem, when the user accesses a route, if the asset corresponding to that route is not yet loaded, a white screen will appear.
+
+In this case you can show a custom `loading` component by defining a `loading` component before the static resource is loaded.
+
+To further improve the user experience and reduce time of loading, Modern.js supports defining the `prefetch` property on the Link component to load static resources and data in advance, with three optional values for the `prefetch` property:
+
+```
+<Link prefetch="intent" to="page">
+```
+
+:::info
+- This feature is currently only supported in Webpack projects, not in Rspack projects.
+- Prefetching of data will only prefetch the data returned from the data loader of the SSR project.
+
+:::
+
+- `none`, the default value, will not do prefetch, no additional behavior.
+- `intent`, the value we recommend for most scenarios, will automatically start loading the corresponding resources and the data defined in the data loader when you mouse over the Link, and will automatically unload it when the mouse is moved away. In our tests, even a direct click can reduce the loading time by about 200ms.
+- `render`, when the Link component renders, it will load the corresponding resources and the data defined in the data loader.
+
 ## Self-controlled routing
 
 With `src/App.tsx` as the agreed entry, Modern.js will not do additional operations with multiple routes, developers can use the React Router 6 API for development by themselves, for example:
@@ -367,7 +387,7 @@ export default () => {
 ```
 
 :::note
-Modern.js has a series of resource loading and rendering optimizations to the default convention-based routing, and provides out-of-the-box SSR capabilities,  when using self-directed routing, need to be packaged by the developer, and it is recommended that developers use convention-based routing.
+Modern.js has a series of resource loading and rendering optimizations to the default convention-based routing, and provides out-of-the-box SSR capabilities, when using self-directed routing, need to be packaged by the developer, and it is recommended that developers use convention-based routing.
 
 :::
 

package/docs/en/guides/concept/entries.mdx

@@ -132,9 +132,9 @@ The content of the file generated by Modern.js is as follows:
 ```js
 import React from 'react';
 import ReactDOM from 'react-dom/client';
-import customBootstrap from '@_edenx_src/index.tsx';
-import App from '@_edenx_src/App';
-import { router, state } from '@edenx/runtime/plugins';
+import customBootstrap from '@_modern_js_src/index.tsx';
+import App from '@_modern_js_src/App';
+import { router, state } from '@modern-js/runtime/plugins';
 
 const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
 const MOUNT_ID = 'root';

package/docs/en/guides/get-started/introduction.mdx

@@ -9,7 +9,27 @@ sidebar_position: 1
 
 Currently, Modern.js includes three solutions, each targeting at different development scenarios: web application development, npm package development, and document site development:
 
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/Solutions-en-0945.png)
+import { SolutionCards } from '@site/src/components/SolutionCards';
+
+<SolutionCards
+  cards={[
+    {
+      title: 'Modern.js Framework',
+      description: 'For web application development',
+      link: 'http://modernjs.dev/en/',
+    },
+    {
+      title: 'Modern.js Module',
+      description: 'For npm package development',
+      link: 'http://modernjs.dev/module-tools/en/',
+    },
+    {
+      title: 'Modern.js Doc',
+      description: 'For document site development',
+      link: 'http://modernjs.dev/doc-tools/',
+    },
+  ]}
+/>
 
 As a part of the Modern.js engineering system, each of these solutions can be used separately and has its own independent documentation site. Developers can choose one or more solutions as needed.
 

package/docs/en/guides/get-started/quick-start.mdx

@@ -7,39 +7,22 @@ sidebar_position: 2
 
 ## Environment
 
-### Node.js
+import Prerequisites from "@site-docs-en/components/prerequisites"
 
-Requires [Node.js LTS](https://github.com/nodejs/Release) and ensures that the Node version is greater than or equal to 14.19.0, 16.x version is recommended.
-
-Modern.js recommend installing [nvm](https://github.com/nvm-sh/nvm#install--update-script) in the development environment and integrating [script to automatically switch node versions](https://github.com/nvm-sh/nvm#deeper-shell-integration) in the shell.
-
-Then there is a `.nvmrc` file with the content of `lts/fermium` or `lts/gallium` in the root directory of the repository, it will automatically install or switch to the correct Node.js version when entering the repository.
-
-### pnpm
-
-[pnpm](https://pnpm.io/installation) is recommended for package management.
-
-```bash
-npm install -g pnpm@7
-```
-
-:::note
-Modern.js also supports other package managers, such as `yarn` or `npm`.
-
-:::
+<Prerequisites />
 
 ## Installation
 
-Modern.js provides the `@modern-js/create` tool to create projects. Don't install globally, use `npx` to run on demand.
+Modern.js provides the `@modern-js/create` tool for creating new projects. You can use `npx` to run it.
 
-Projects can be created using an existing empty directory:
+You can create the project in an existing empty directory:
 
 ```bash
 mkdir myapp && cd myapp
 npx @modern-js/create
 ```
 
-Projects can also be created directly from the new directory:
+You can also directly create the project as a new folder:
 
 ```bash
 npx @modern-js/create myapp
@@ -161,4 +144,4 @@ Open http://localhost:8000/ in the browser and the content should be the same as
 
 ## Deploy
 
-After the local verification is completed, the products under `dist/` can be organized into the structure required by the server for deployment.
+Once the local verification is complete, the outputs under `dist` folder can be organized into the structure required by the server for deployment.