@modern-js/main-doc 0.0.0-next-1681194540734 → 0.0.0-next-1681214624937

package/CHANGELOG.md

@@ -1,12 +1,19 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-1681194540734
+## 0.0.0-next-1681214624937
 
 ### Patch Changes
 
+- e91ec97bd0: feat(app-tools): export mergeConfig function
+
+  feat(app-tools): 导出 mergeConfig 函数
+
+- 42700c13bd: chore: improve ssr docs, add more use case for node/web code split
+  chore: 优化 ssr 文档，为 node/web 代码分割添加更多使用场景
 - Updated dependencies [1feacdc7d6]
 - Updated dependencies [348306d413]
-  - @modern-js/builder-doc@0.0.0-next-1681194540734
+- Updated dependencies [42700c13bd]
+  - @modern-js/builder-doc@0.0.0-next-1681214624937
 
 ## 2.12.0
 

package/docs/en/apis/app/runtime/core/use-loader.mdx

@@ -5,6 +5,10 @@ title: useLoader
 
 Isomorphic API, usually used to make asynchronous requests. When SSR, the server level uses `useLoader` to prefetch the data, and the browser side also reuses this part of the data.
 
+:::tip
+When using Rspack as the bundler, the useLoader API is not currently supported.
+:::
+
 ## Usage
 
 ```ts

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/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/routes.mdx

@@ -345,6 +345,28 @@ export const config = (): AppConfig => {
 };
 ```
 
+### 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:

package/docs/zh/apis/app/runtime/core/use-loader.mdx

@@ -5,6 +5,10 @@ title: useLoader
 
 一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
 
+:::tip
+在使用 Rspack 作为打包工具时，暂不支持使用 useLoader API。
+:::
+
 ## 使用姿势
 
 ```ts

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

@@ -19,17 +19,33 @@ Modern.js 不支持同时在 package.json 中和 modern.config.ts 中配置同
 
 ## 在配置文件中配置
 
-Modern.js 的配置文件定义在项目的根目录下，支持 `.js`, `.ts` 和 `.mjs` 格式：
+Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js` 和 `.mjs` 格式：
 
-- `modern.config.js`
 - `modern.config.ts`
+- `modern.config.js`
 - `modern.config.mjs`
 
-### modern.config.js
+### modern.config.ts（推荐）
+
+我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
+
+从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
 
-`modern.config.js` 中可以使用 JavaScript 语法，因此比 `package.json` 更加灵活。
+### modern.config.js
 
-比如，你可以在 `modern.config.js` 中定义函数类型的配置选项：
+如果你在开发一个非 TypeScript 项目，可以使用 .js 格式的配置文件：
 
 ```js title="modern.config.js"
 export default {
@@ -51,24 +67,6 @@ export default {
 };
 ```
 
-### modern.config.ts（推荐）
-
-我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
-
-从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  source: {
-    alias: {
-      '@common': './src/common',
-    },
-  },
-});
-```
-
 ### 导出配置函数
 
 Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。
@@ -134,7 +132,7 @@ $ modern build -c modern.prod.config.js
 
 ## 在 package.json 中配置（不推荐）
 
-除了配置文件外，也可以在 `package.json` 中的 `modernConfig` 字段下设置配置选项，如：
+除了配置文件外，你也可以在 `package.json` 中的 `modernConfig` 字段下设置配置项，如：
 
 ```json title="package.json"
 {
@@ -200,3 +198,47 @@ modern.config.local.ts
 modern.config.local.js
 modern.config.local.mjs
 ```
+
+## 合并多份配置
+
+在某些情况下，你可能需要将多份配置合并为一份配置，此时你可以使用 `mergeConfig` 工具函数来合并多个配置。
+
+`mergeConfig` 函数接受一个数组作为参数，数组中的每一项都是一个配置对象，`mergeConfig` 会将数组中的每一项配置对象进行深层合并，自动将多个函数项合并为数组，最终返回一个合并后的配置对象。
+
+### 示例
+
+```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]);
+```
+
+在以上示例中，合并后的配置对象为：
+
+```ts
+const mergedConfig = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: [() => console.log('config1'), () => console.log('config2')],
+  },
+};
+```

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

@@ -215,16 +215,23 @@ const App = () => {
 export default App;
 ```
 
-在组件文件中引入 Node API，通常情况下是因为使用了 Data Loader，例如：
+在组件文件中引入 Node API，通常情况下是因为使用了 `useLoader`，例如：
 
 ```ts
 import fse from 'fs-extra';
-export const loader = () => {
-  const file = fse.readFileSync('./myfile');
-  return {
-    ...
-  };
+import { useLoader } from '@modern-js/runtime'
+
+const App = () => {
+  const { data } = useLoader(async () => {
+    const file = fse.readFileSync('./myfile');
+    return {
+      ...
+    };
+  })
+
+  return <div>Hello World</div>;
 };
+export default App;
 ```
 
 ### 环境变量区分
@@ -239,16 +246,32 @@ if (process.env.MODERN_TARGET === 'browser') {
 }
 ```
 
+开发环境打包后，SSR 产物和 CSR 产物会被编译成以下内容。因此 SSR 环境中不会再因为 Web API 报错：
+
+```ts
+// SSR 产物
+if (false) {
+}
+
+// CSR 产物
+if (true) {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
 :::note
 更多内容可以查看[环境变量](/guides/basic-features/env-vars)。
-
 :::
 
 ### 文件后缀区分
 
-但例如第二种情况，Treeshaking 的方式并不能保证代码被完全分离。Modern.js 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
+但例如第二种情况，在代码中引入了 `fs-extra`，它内部有使用了 Node API 的副作用，如果直接引用到组件中，会造成 CSR 加载报错。
+
+环境变量的方式并不能在这种情况下生效，Modern.js 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
 
-例如在代码中引入了 `fs-extra`，这时候直接引用到组件中，会造成 CSR 加载报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
+可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
 
 ```ts title="compat.ts"
 export const readFileSync: any = () => {};
@@ -273,7 +296,27 @@ export const loader = () => {
 
 ### 独立文件
 
-上述两种方式，都会为开发者带来一些心智负担。Modern.js 基于[嵌套路由](/guides/basic-features/routes)开发设计了[更简单的方案](/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+上述两种方式，都会为开发者带来一些心智负担。在真实的业务中，我们发现大多数的 Node / Web 代码混用都出现在数据请求中。
+
+因此，Modern.js 基于[嵌套路由](/guides/basic-features/routes)开发设计了[更简单的方案](/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+
+我们可以通过独立文件来分离**数据请求**与**组件代码**。在 `routes/page.tsx` 中编写组件逻辑，在 `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 {
+    ...
+  };
+}
+```
 
 ## 接口请求
 
@@ -307,7 +350,7 @@ Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
 
 ### 异步获取数据
 
-```ts title='page.loader.ts'
+```ts title="page.loader.ts"
 import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
 
 interface User {
@@ -336,11 +379,11 @@ export default ({ params }: LoaderFunctionArgs) => {
 ```
 
 `user` 是一个 Promise 类型的对象，表示需要异步获取的数据，通过 `defer` 处理需要异步获取的 `user`。注意，`defer` 必须接收一个对象类型的参数，
-因此， 传入 `defer` 的参数为 `{data: user}`。
+因此， 传入 `defer` 的参数为：`{ data: user }`
 
 `defer` 还可以同时接收异步数据和同步数据。例如：
 
-```ts title='page.loader.ts'
+```ts title="page.loader.ts"
 // 省略部分代码
 
 export default ({ params }: LoaderFunctionArgs) => {
@@ -374,7 +417,7 @@ export default ({ params }: LoaderFunctionArgs) => {
 
 通过 `Await` 组件，可以获取到 Data Loader 中异步返回的数据，然后进行渲染。例如：
 
-```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';
@@ -454,7 +497,7 @@ export default Page;
 `Await` 组件的 `errorElement` 属性，可以用来处理当 Data Loader 执行时，或者子组件渲染时抛出的错误。
 例如，我们故意在 Data Loader 函数中抛出错误：
 
-```ts title='page.loader.ts'
+```ts title="page.loader.ts"
 import { defer } from '@modern-js/runtime/router';
 
 export default () => {
@@ -470,7 +513,7 @@ export default () => {
 
 然后通过 `useAsyncError` 获取错误，并将用于渲染错误信息的组件赋值给 `Await` 组件的 `errorElement` 属性：
 
-```tsx title='page.ts'
+```tsx title="page.ts"
 import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
 import { Suspense } from 'react';
 

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

@@ -424,6 +424,29 @@ export const init = (context: RuntimeContext) => {
 };
 ```
 
+### Prefetch
+
+在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片，当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
+这种情况下你可以通过定义 `loading` 组件，在静态资源加载完成前，展示一个自定义的 `loading` 组件。
+
+为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载， `prefetch` 属性有三个可选值：
+
+```
+<Link prefetch="intent" to="page">
+```
+
+:::info
+- 该功能目前仅在 Webpack 项目中支持，Rspack 项目暂不支持。
+- 对数据的预加载目前只会预加载 SSR 项目中 [data loader](/guides/basic-features/data-fetch) 中返回的数据。
+
+:::
+
+- `none`， 默认值，不会做 prefetch，没有任何额外的行为。
+- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 data loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是直接点击，也能减少大约 200ms 的加载时间。
+- `render`，当 Link 组件渲染时，就会加载对应的分片和 data loader 中定义的数据。
+
+
+
 ## 自控式路由
 
 以 `src/App.tsx` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发，例如：
@@ -469,3 +492,20 @@ export default defineConfig({
   },
 });
 ```
+
+### 常见问题
+
+1. 产物中的代码是 es2015+ 的，期望产物中是 es5 的代码
+
+react-router^6 的目前默认产物是 es2020 的，如果需要产物中是 es5 的代码，可以配置 `source.include`，让 react-router 相关包经过 bundler 编译 ：
+
+```
+source: {
+  source: {
+    include: [/@remix-run\/router/, /react-router-dom/, /react-router/],
+  }
+}
+```
+
+
+

package/package.json

@@ -11,13 +11,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-next-1681194540734",
+  "version": "0.0.0-next-1681214624937",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "0.0.0-next-1681194540734"
+    "@modern-js/builder-doc": "0.0.0-next-1681214624937"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -29,9 +29,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "0.0.0-next-1681194540734",
-    "@modern-js/doc-tools": "0.0.0-next-1681194540734",
-    "@modern-js/doc-plugin-auto-sidebar": "0.0.0-next-1681194540734"
+    "@modern-js/builder-doc": "0.0.0-next-1681214624937",
+    "@modern-js/doc-tools": "0.0.0-next-1681214624937",
+    "@modern-js/doc-plugin-auto-sidebar": "0.0.0-next-1681214624937"
   },
   "scripts": {
     "dev": "modern dev",