@modern-js/main-doc 2.5.0 → 2.6.0

package/zh/guides/advanced-features/rspack-start.mdx

@@ -0,0 +1,69 @@
+---
+title: 使用 Rspack
+sidebar_position: 12
+---
+
+# 使用 Rspack
+
+[Rspack](https://www.rspack.org/) 是字节跳动 Web Infra 团队自研的 Rust Bundler，核心架构对齐 webpack 实现，并对社区常用的构建能力做了开箱即用的支持。
+
+Rspack 通过以下方式来提升编译性能：
+
+- 高度 LTO 优化的 Native code。
+- 充分利用多核优势，整个编译过程充分进行多线程优化。
+- 基于请求的按需编译（Lazy Compilation），减小每次编译的模块数目，以提升冷启动的速度。
+
+## 初始化 rspack 项目
+
+Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为**rspack**，即可创建一个 rspack 项目:
+
+```bash
+$ npx @modern-js/create myapp
+? 请选择你想创建的工程类型 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+? 请选择构建工具 rspack
+```
+
+项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目。更多项目信息可参考[快速上手](/guides/get-started/quick-start.html)。
+
+:::tip
+使用 rspack 作为打包工具时，以下功能暂不支持使用:
+
+- 服务端渲染（SSR）
+- 静态站点生成（SSG）
+- 微前端（Micro Frontend）
+- Storybook 调试
+
+:::
+
+## 从 webpack 迁移至 rspack
+
+通过执行 `pnpm run new` 可启用 rspack 构建：
+
+```bash
+$ pnpm run new
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「rspack 构建」
+```
+
+执行命令后，在 modern.config.ts 中开启 rspack 构建：
+
+```ts title=modern.config.ts
+import appTools, { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig<'rspack'>({
+  runtime: {
+    router: true,
+  },
+  plugins: [
+    appTools({
+      bundler: 'experimental-rspack',
+    }),
+  ],
+});
+```
+
+:::tip
+从 webpack 迁移至 rspack，会有一些构建和配置能力上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
+:::

package/zh/guides/advanced-features/ssg.mdx

@@ -37,14 +37,14 @@ SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
 ```
 .
 ├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
 ```
 
 上述文件目录将会生成以下三条路由：

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

@@ -20,8 +20,8 @@ sidebar_position: 3
 
 Modern.js 中提供了 Data Loader，方便开发者在 SSR、CSR 下同构的获取数据。每个路由模块，如 `layout.tsx` 和 `page.tsx` 都可以定义自己的 Data Loader：
 
-```ts title="src/routes/page.tsx"
-export const loader = () => {
+```ts title="src/routes/page.loader.ts"
+export default () => {
   return {
     message: 'Hello World',
   };
@@ -31,6 +31,7 @@ export const loader = () => {
 在组件中可以通过 Hooks API 的方式获取 `loader` 函数返回的数据：
 
 ```tsx
+import { useLoaderData } from '@modern-js/runtime/router'
 export default () => {
   const data = useLoaderData();
   return <div>{data.message}</div>;

package/zh/guides/basic-features/alias.mdx

@@ -23,10 +23,10 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 ```bash
 .
 ├── common
-│   ├── styles
-│   │   └── base.css
-│   └── utils
-│       └── index.ts
+│   ├── styles
+│   │   └── base.css
+│   └── utils
+│       └── index.ts
 ├── App.tsx
 ```
 

package/zh/guides/basic-features/data-fetch.mdx

@@ -82,9 +82,9 @@ export default async (): Promise<ProfileData> => {
 
 ```tsx
 // routes/user/[id]/page.loader.ts
-import { LoaderArgs } from '@modern-js/runtime/router';
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
-export default async ({ params }: LoaderArgs) => {
+export default async ({ params }: LoaderFunctionArgs) => {
   const { id } = params;
   const res = await fetch(`https://api/user/${id}`);
   return res.json();
@@ -101,9 +101,9 @@ export default async ({ params }: LoaderArgs) => {
 
 ```tsx
 // routes/user/[id]/page.loader.ts
-import { LoaderArgs } from '@modern-js/runtime/router';
+import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
-export default async ({ request }: LoaderArgs) => {
+export default async ({ request }: LoaderFunctionArgs) => {
   const url = new URL(request.url);
   const userId = url.searchParams.get('id');
   return queryUser(userId);

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

@@ -109,7 +109,7 @@ export default () => {
 .
 └── routes
     ├── blog
-    │   └── page.tsx
+    │   └── page.tsx
     ├── layout.tsx
     ├── page.tsx
     └── user
@@ -156,9 +156,9 @@ export default () => {
 ```
 └── routes
     ├── [id]
-    │   └── page.tsx
+    │   └── page.tsx
     ├── blog
-    │   └── page.tsx
+    │   └── page.tsx
     └── page.tsx
 ```
 
@@ -181,7 +181,7 @@ export default () => {
 └── routes
     ├── $.tsx
     ├── blog
-    │   └── page.tsx
+    │   └── page.tsx
     └── page.tsx
 ```
 
@@ -248,9 +248,9 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 .
 └── routes
     ├── blog
-    │   ├── [id]
-    │   │   └── page.tsx
-    │   └── page.tsx
+    │   ├── [id]
+    │   │   └── page.tsx
+    │   └── page.tsx
     ├── layout.tsx
     ├── loading.tsx
     └── page.tsx
@@ -292,6 +292,22 @@ Modern.js 建议必须有根 layout 和根 loading。
 
 同理，当路由从 `/` 或者 `/blog` 跳转到 `/blog/123` 时，如果 `blog/[id]/page` 组件的 JS Chunk 还未加载，也会先展示 `loading.tsx` 中导出的组件 UI。
 
+### 路由重定向
+
+可以通过创建 [`data loader`](/guides/basic-features/data-fetch) 文件做路由的重定向，如有文件 `routes/user/page.tsx`，想对这个文件对应的路由做重定向，可以创建 `routes/user/page.loader.ts` 文件：
+
+```ts title="routes/user/page.loader.ts"
+import { redirect } from "@edenx/runtime/router"
+
+export default () => {
+  const user = await getUser();
+  if(!user){
+    return redirect('/login');
+  }
+  return null;
+}
+```
+
 ### 错误处理
 
 `routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。

package/zh/guides/concept/builder.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 **Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
 
-Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 Rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
 
 ## 构建架构
 
@@ -14,7 +14,7 @@ Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向
 
 - 上层研发框架：Modern.js。
 - 通用构建引擎：Modern.js Builder。
-- 底层打包工具：webpack 和 Rspack。
+- 底层打包工具：webpack 和 rspack。
 
 <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
 

package/zh/guides/get-started/quick-start.mdx

@@ -96,9 +96,9 @@ info    File sizes after production build:
 .
 ├── asset-manifest.json
 ├── html
-│   └── main
+│   └── main
 ├── loader-routes
-│   └── main
+│   └── main
 ├── modern.config.json
 ├── route.json
 └── static

package/zh/guides/topic-detail/micro-frontend/c03-main-app.mdx

@@ -149,7 +149,7 @@ export default () => {
 然后在主应用中使用 `useModuleApp` 方法获取 `MApp` 组件, 并在主应用渲染 `MApp`。
 
 ```tsx title=主应用：App.tsx
-import { useModuleApp } from '@modern-js/plugin-runtime';
+import { useModuleApp } from '@modern-js/plugin-garfish/runtime';
 
 function App() {
   const { MApp } = useModuleApps();

package/zh/tutorials/first-app/c07-container.mdx

@@ -255,23 +255,23 @@ export default Index;
 ├── package.json
 ├── pnpm-lock.yaml
 ├── src
-│   ├── components
-│   │   ├── Avatar
-│   │   │   └── index.tsx
-│   │   └── Item
-│   │       └── index.tsx
-│   ├── containers
-│   │   └── Contacts.tsx
-│   ├── models
-│   │   └── contacts.ts
-│   ├── modern-app-env.d.ts
-│   ├── routes
-│   │   ├── archives
-│   │   │   └── page.tsx
-│   │   ├── layout.tsx
-│   │   └── page.tsx
-│   └── styles
-│       └── utils.css
+│   ├── components
+│   │   ├── Avatar
+│   │   │   └── index.tsx
+│   │   └── Item
+│   │       └── index.tsx
+│   ├── containers
+│   │   └── Contacts.tsx
+│   ├── models
+│   │   └── contacts.ts
+│   ├── modern-app-env.d.ts
+│   ├── routes
+│   │   ├── archives
+│   │   │   └── page.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   └── styles
+│       └── utils.css
 └── tsconfig.json
 ```
 

package/zh/tutorials/first-app/c08-entries.mdx

@@ -29,29 +29,29 @@ title: 添加应用入口
 ├── package.json
 ├── pnpm-lock.yaml
 ├── src
-│   ├── modern-app-env.d.ts
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── myapp
-│       ├── components
-│       │   ├── Avatar
-│       │   │   └── index.tsx
-│       │   └── Item
-│       │       └── index.tsx
-│       ├── containers
-│       │   └── Contacts.tsx
-│       ├── models
-│       │   └── contacts.ts
-│       ├── routes
-│       │   ├── archives
-│       │   │   └── page.tsx
-│       │   ├── layout.tsx
-│       │   └── page.tsx
-│       └── styles
-│           └── utils.css
+│   ├── modern-app-env.d.ts
+│   ├── landing-page
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       └── page.tsx
+│   └── myapp
+│       ├── components
+│       │   ├── Avatar
+│       │   │   └── index.tsx
+│       │   └── Item
+│       │       └── index.tsx
+│       ├── containers
+│       │   └── Contacts.tsx
+│       ├── models
+│       │   └── contacts.ts
+│       ├── routes
+│       │   ├── archives
+│       │   │   └── page.tsx
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       └── styles
+│           └── utils.css
 └── tsconfig.json
 ```
 

package/en/apis/app/commands/_category_.json

@@ -1,5 +0,0 @@
-{
-  "label": "Commands",
-  "position": 0,
-  "collapsed": false
-}

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

@@ -1,39 +0,0 @@
----
-sidebar_position: 5
----
-# build
-
-```bash
-Usage: modern build [options]
-
-build application
-
-Options:
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --analyze             analyze the bundle and view size of each module
-```
-
-`modern build` command will by default build production in `dist/`.
-
-you can configure the [`output.distPath`](/configure/app/output/dist-path) specifies the output directory for the product.
-
-## Analyze Bundle
-
-execute `npx modern build --analyze` command，can produce an HTML file that analyzes the volume of the bundle while packaging the production code:
-
-```
-Bundle Analyzer saved report to /example/dist/report.html
-File sizes after production build:
-
-  122.35 KB  dist/static/js/885.1d4fbe5a.js
-  2.3 KB     dist/static/js/main.4b8e8d64.js
-  761 B      dist/static/js/runtime-main.edb7cf35.js
-  645 B      dist/static/css/main.0dd3ecc1.css
-```
-
-Open the above HTML file in the browser, you can see the tile diagram of the packaged product, and perform package volume analysis and optimization:
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
-
-> this features based on [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).

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

@@ -1,61 +0,0 @@
----
-sidebar_position: 1
----
-
-# dev / start
-
-```bash
-Usage: modern dev / modern start [options]
-
-Development commands
-
-Options:
-  -e --entry <entry>    compiler by entry
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --analyze             analyze the bundle and view size of each module
-  --api-only            only start API service
-```
-
-`modern dev` start a development server，watch file change，default support React Fast Refresh:
-
-`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
-
-```bash
-$ modern dev
-
-info    Starting dev server...
-info    App running at:
-
-  > Local:    http://localhost:8080/
-  > Network:  http://192.168.0.1:8080/
-```
-
-## Compile Partial Pages
-
-In multi-page (MPA) projects, the `--entry` option can be added to specify one or more pages to compile. In this way, only part of the code in the project will be compiled, and the dev startup speed will be faster.
-
-For example, execute `modern dev --entry`, the entry selector will be displayed in the command line interface:
-
-```bash
-$ modern dev --entry
-
-? Please select the entry that needs to be built
-❯ ◯ foo
-  ◯ bar
-  ◯ baz
-```
-
-For example, if you select the `foo` entry, only the code related to the `foo` entry will be compiled, and the code of other pages will not be compiled.
-
-### Specify the page by parameter
-
-You can also specify the page name through parameters after `--entry`, and the names of multiple pages can be separated by commas.
-
-```bash
-# Compile foo page
-modern dev --entry foo
-
-# Compile foo and bar pages
-modern dev --entry foo,bar
-```

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

@@ -1,61 +0,0 @@
----
-sidebar_position: 7
----
-# inspect
-
-```
-Usage: modern inspect [options]
-
-Options:
-  --env <env>           view the configuration in the target environment (default: "development")
-  --output <output>     Specify the path to output in the dist (default: "/")
-  --verbose             Show the full function in the result
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-```
-
-`modern inspect` command used to view the [Modern.js Builder config](https://modernjs.dev/builder/en/guide/basic/builder-config.html) and webpack config of the project.
-
-After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
-
-- `builder.config.js`: The Modern.js Builder config to use at build time.
-- `webpack.config.web.js`: The webpack config used by to use at build time.
-
-```bash
-➜ npx modern inspect
-
-Inspect config succeed, open following files to view the content:
-
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
-```
-
-## Configuration Env
-
-By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
-
-```bash
-modern inspect --env production
-```
-
-## Verbose content
-
-By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
-
-```bash
-modern inspect --verbose
-```
-
-### SSR Configuration
-
-If the project has enabled SSR, an additional `webpack.config.node.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
-
-```bash
-➜ npx modern inspect
-
-Inspect config succeed, open following files to view the content:
-
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
-  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
-```

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

@@ -1,19 +0,0 @@
----
-sidebar_position: 4
-title: lint
----
-# lint
-
-```bash
-Usage: modern lint [options] [...files]
-
-lint and fix source files
-
-Options:
-  --no-fix    disable auto fix source file
-  -h, --help  display help for command
-```
-
-Run ESLint to check the syntax of the code. Normally, only the part of the code modified by this commit needs to be checked by `lint-staged` during the `git commit` phase.
-
-- `--no-fix` close auto fix by lint.

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

@@ -1,55 +0,0 @@
----
-sidebar_position: 2
----
-# new
-
-```bash
-Usage: modern new [options]
-
-Execution Generator in App
-
-Options:
-  -d, --debug            using debug mode to log something (default: false)
-  -c, --config <config>  set default generator config(json string)
-  --dist-tag <tag>       use specified tag version for its generator
-  --registry             set npm registry url to run npm command
-  -h, --help             show command help
-```
-
-The `modern new` command is used to enable features to an existing project.
-
-For example, add application entry, enable some optional features such as Tailwind CSS, micro frontend, etc.
-
-### Add Entry
-
-In the project, execute the `new` command to add entries as follows:
-
-```bash
-$ npx modern new
-? Action Create project element
-? Create project element New "entry"
-? Entry name entry
-```
-
-### Enable Features
-
-In the project, execute the `new` command to enable features as follows:
-
-```bash
-$ npx modern new
-? Action Enable features
-? Enable features (Use arrow keys)
-❯ Enable Tailwind CSS
-  Enable BFF
-  Enable SSG
-  Enable Micro Frontend
-  Enable Unit Test / Integration Test
-  Enable Visual Testing (Storybook)
-```
-
-:::caution
-The `--config` parameter needs to use a JSON string.
-
-pnpm does not support the use of JSON strings as parameter values currently. Use `npm new` to turn on.【[Relate Issue](https://github.com/pnpm/pnpm/issues/3876)】
-
-:::

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

@@ -1,27 +0,0 @@
----
-sidebar_position: 6
----
-# serve
-
-```bash
-Usage: modern serve [options]
-
-run server
-
-Options:
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --api-only            only run API service
-```
-
-Usually use the `modern serve` command to enable project run in the production environment, and you need to execute the [`build'](/apis/app/commands/build) command in advance to build the product.
-
-By default, the project will run in `localhost:8080`, you can modify the Server port number with `server.port`:
-
-```js
-export default defineConfig({
-  server: {
-    port: 8081,
-  },
-});
-```

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

@@ -1,35 +0,0 @@
----
-sidebar_position: 3
----
-# test
-
-```bash
-Usage: modern test [options]
-
-Options:
-  -h, --help  show command help
-```
-
-:::caution
-`modern test` command need to execute the `new` command in advance to enable the `unit test/integration test`.
-
-:::
-
-`modern test` command will automatically run the test cases, the effect is as follows:
-
-```bash
-$ npx modern test
- PASS  src/tests/index.test.ts
-  The add method
-    ✓ should work fine. (2ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        0.994 s, estimated 1 s
-```
-
-:::info
-files match `*.test.(js|ts)` in `api/` or `src/` will be recognized as test cases by default.
-
-:::