npm - @modern-js/main-doc - Versions diffs - 2.51.0 → 2.53.0 - Mend

@modern-js/main-doc 2.51.0 → 2.53.0

Files changed (68) hide show

package/docs/en/apis/app/runtime/web-server/unstable_middleware.mdx CHANGED Viewed

@@ -12,7 +12,7 @@ UnstableMiddleware will replace [Middleware](/apis/app/runtime/web-server/middle
 ```ts title="server/index.ts"
 import { UnstableMiddleware } from '@modern-js/runtime/server';
-export const unstableMiddlewares: UnstableMiddleware[] = [];
+export const unstableMiddleware: UnstableMiddleware[] = [];
 ```
 ## Types
@@ -74,7 +74,7 @@ const time: UnstableMiddleware = async (c, next) => {
   console.log(`${end - start}`);
 };
-export const unstableMiddlewares: UnstableMiddleware = [time];
+export const unstableMiddleware: UnstableMiddleware[] = [time];
 ```
 ### Injecting Server Data for DataLoader Consumption
@@ -101,7 +101,7 @@ const setPayload: UnstableMiddleware = async (
   await next();
 };
-export const unstableMiddlewares: UnstableMiddleware = [setPayload];
+export const unstableMiddleware: UnstableMiddleware[] = [setPayload];
 ```
 ```ts title="src/routes/page.data.ts"
@@ -130,5 +130,31 @@ const auth: UnstableMiddleware = async (c, next) => {
   await next();
 };
-export const unstableMiddlewares: UnstableMiddleware = [auth];
+export const unstableMiddleware: UnstableMiddleware[] = [auth];
+```
+### Modify Response
+```ts
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+const modifier: UnstableMiddleware = async (c, next) => {
+  await next();
+  const { response } = c;
+  const text = await response.text();
+  const newText = text.replace('<html>', `<html lang="${language}">`);
+  const newheaders = response.headers;
+  newheaders.set('x-custom-value', 'modern');
+  c.response = c.body(newText, {
+    status: response.status,
+    headers: newheaders,
+  });
+};
+export const unstableMiddleware: UnstableMiddleware[] = [modifier];
 ```

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

@@ -90,7 +90,9 @@ Modern.js provides a set of APIs by default for projects to use:
 import { Middleware } from '@modern-js/runtime/server';
 export const middleware: Middleware = (context, next) => {
-  const { source: { req, res } } = context;
+  const {
+    source: { req, res },
+  } = context;
   console.log(req.url);
   next();
 };
@@ -108,7 +110,7 @@ Projects should follow these best practices when using Middleware:
 **In general, in CSR projects, using Hook can basically meet all the needs of simple scenarios. In SSR projects, Middleware can be used for more complex Node extensions.**
-### UnstableMiddleware
+### Unstable Middleware
 Modern.js will provide new Middleware to add pre-processing middleware to the Web Server, supporting the execution of custom logic before and after handling the page.

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

@@ -155,6 +155,8 @@ function loader() {
 ### Error Handling
+#### Basic Usage
 In the `loader` function, errors can be handled by throwing an `error` or a `response`. When an error is thrown in the `loader` function, Modern.js will stop executing the code in the current `loader` and switch the front-end UI to the defined [`ErrorBoundary`](/guides/basic-features/routes#error-handling) component:
 ```tsx
@@ -182,6 +184,32 @@ const ErrorBoundary = () => {
 export default ErrorBoundary;
 ```
+#### Practice
+In an SSR project you can control the status code of a page and display the corresponding UI by `throw response` in the data loader, as in the following example, where there is one loader for the entire routing route
+For example, if there is a loader in the entire routing route that throws a response, the status code of the page will be consistent with this `response` and the UI of the page will switch to `ErrorBoundary`.
+```ts
+// routes/user/profile/page.data.ts
+export async function loader() {
+  const user = await fetchUser();
+  if(!user){
+    throw new Response('The user was not found', { status: 404 });
+  }
+  return user;
+}
+// routes/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as { data: string };
+  return <div className="error">{error.data}</div>;
+};
+export default ErrorBoundary;
+```
 ### Get data from parent component
 In many cases, child components need to access data in the parent component `loader`. You can easily get the data from the parent component using `useRouteLoaderData`:

package/docs/en/guides/basic-features/deploy.mdx CHANGED Viewed

@@ -2,18 +2,20 @@
 sidebar_position: 15
 ---
-# Deploy
+# Deploy Application
-Currently, Modern.js can run in the node.js environment, you can host it yourself. At the same time, Modern.js officially supports deployment on the Netlify platform.
+Currently, Modern.js offers two deployment way:
+- You can host your application in a container that includes a Node.js environment on your own, which provides flexibility for the deployment of the application.
+- You can also deploy your application through a platform. Currently, Modern.js supports the [Netlify](https://www.netlify.com/) and [Vercel](https://vercel.com/).
 :::info
-Currently Modern.js only supports running in node.js environments, support for other runtime environments will be provided in a later version.
+Currently, Modern.js only supports running in a Node.js environment. Support for more runtime environments will be provided in the future.
 :::
-## Commands to build products
+## Build Deployment Products
-Running the `modern deploy` command will automatically build the output file for the production environment. This process includes optimizing the output file and its dependencies, and detecting the current deployment platform and automatically generating a product that will run on that platform.
+Running the `modern deploy` command will automatically produce deployment products. This process includes optimizing Bundler build products and their dependencies, detecting the current deployment platform, and automatically generating deployment products that can run on that platform.
 If you want to generate and test the output locally for a specific deployment platform, you can specify the platform by setting the environment variable: `modern deploy`:
@@ -33,11 +35,12 @@ When deploying on the deployment platforms officially supported by Modern.js, th
 By default, Modern.js outputs builds that can be run in a Node.js environment when no Modern.js-supported deployment platform is detected.
 Use the following command to build the project:
 ```bash
 npx modern deploy
 ```
-When running the `modern deploy` command, Modern.js will generate runnable products and output the following content:
+When running the `modern deploy` command, Modern.js will generate runnable products and output the following content in terminal:
 ```bash
 Static directory: `.output/static`
@@ -56,35 +59,35 @@ PORT=3000 node .output/index
 ### Monorepo
-For the Monorepo project, in addition to building our current project, we also need to build other repositories that the current project depends on.
+For Monorepo projects, in addition to building the current project, it is also necessary to build other sub-projects in the repository that the current project depends on.
-We assume that the name in the `package.json` of the current project is `app`. Taking pnpm as an example of a monorepo management tool, you can add the following command to the `package.json` of the current project to build products for the current project:
+Assume that the name in the `package.json` of the current project is `app`. Taking pnpm as an example of a monorepo management tool, you can add the following command to the `package.json` of the current project to build products for the current project:
 ```json title="app/package.json"
 {
   "scripts": {
-    "deploy": "modern deploy",
-    "deploy:app": "pnpm --filter 'app^...' run build && pnpm --filter=app run deploy",
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy",
   }
 }
 ```
-If you use rush to manage repositories, you can add the following command in `package.json`:
+If you use Rush as your Monorepo management tool, you can add the following commands to your `package.json`:
 ```json
 {
   "scripts": {
-    "deploy": "modern deploy",
-    "deploy:app": "rush rebuild --to-except app && rushx deploy",
+    "build:packages": "rush rebuild --to-except app",
+    "deploy": "rushx build:packages && modern deploy",
   }
 }
 ```
-After the build is completed, Modern.js will generate all dependencies in the `.output/node_modules` directory of the project. Similarly, you can run the entire server using `node .output/index`.
+After the build is completed, Modern.js will generate all dependencies in the `.output/node_modules` directory of the project. Similarly, you can run the Modern.js server using `node .output/index`.
 ## Netlify
-Netlify is a popular web development platform designed for building, deploying, and maintaining modern web projects. Deploying on Netlify mainly requires configuring the `netlify.toml` file.
+Netlify is a popular Web development platform designed for building, deploying, and maintaining modern web projects. Deploying on Netlify mainly requires configuring the `netlify.toml` file.
 Depending on the complexity of your project, you can configure it incrementally by this doc.
@@ -93,31 +96,31 @@ Depending on the complexity of your project, you can configure it incrementally
 Add the `netlify.toml` file to the root directory of the current project:
 ```bash
-./
-├── src/
+.
+├── src
 ├── modern.config.ts
 ├── netlify.toml
-├── package.json
+└── package.json
 ```
 Add the following content to `netlify.toml`:
 ```toml
 [build]
   publish = "dist"
-  command = "npm run deploy"
+  command = "modern deploy"
 ```
-Add a project to the Netlify platform and deploy it!
+Now, add a project to the Netlify platform and deploy it!
 ### Full Stack Project
-Full-stack projects refer to projects that use custom servers, SSR, and BFF. These projects need to be deployed on Netlify Functions. Based on the `netlify.toml` file mentioned above,
-add the following configuration:
+Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. These projects need to be deployed on **Netlify Functions**. Based on the `netlify.toml` file mentioned above, add the following configuration:
 ```toml title="netlify.toml"
 [build]
   publish = "dist"
-  command = "npm run deploy"
+  command = "modern deploy"
 [functions]
   directory = ".netlify/functions"
@@ -133,31 +136,40 @@ Currently, Modern.js does not support deployment on Netlify Edge Functions. We w
 ### Monorepo
-For Monorepo projects, in addition to building our current project, we also need to build the dependencies of the current project from other repositories.
-We take a pnpm monorepo repository as an example and deploy the Monorepo project on Netlify.
+:::info
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#Pure Frontend Project) to deploy.
+:::
+For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
-Suppose we have the following Monorepo repository:
+We take a pnpm Monorepo repository as an example and deploy the Monorepo project on Netlify.
+Assuming the directory structure of the Monorepo repository is as follows:
 ```
-./
-├── packages/
-│   ├── app/
+.
+├── packages
+│   ├── app
 │   └── app-dep1
 ├── package.json
 ├── pnpm-lock.yaml
 └── pnpm-workspace.yaml
 ```
-We need to configure Base directory on the netlify platform as `packages/app`:
+You need to configure Base directory on the netlify platform as `packages/app`:
 <img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/netlify-monorepo-basedir.png?x-resource-account=public" />
 Add the following script in `packages/app/package.json`, before executing the deployment command of the `app` repository, first execute the build of other repositories in the workspace:
 ```json
-"scripts": {
-  "deploy:app": "pnpm --filter 'app^...' run build && pnpm --filter=app run deploy",
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy",
+  }
 }
 ```
 Configure the build command in `netlify.toml`:
@@ -165,7 +177,7 @@ Configure the build command in `netlify.toml`:
 ```toml
 [build]
   publish = "dist"
-  command = "npm run deploy:app"
+  command = "npm run deploy"
 [functions]
   directory = ".netlify/functions"
@@ -174,3 +186,101 @@ Configure the build command in `netlify.toml`:
 ```
 Just submit your code and deploy it using the Netlify platform.
+## Vercel
+Vercel is a deployment platform for modern web applications that provides a rich set of features to support deploying static websites, server-side rendered applications, and more. To deploy on Vercel, you usually need to configure the `vercel.json` file, which you can configure incrementally depending on the complexity of your project.
+### Pure Front-end Project
+Add the `vercel.json` file to the root directory of the current project:
+```bash
+./
+├── src
+├── modern.config.ts
+├── vercel.json
+└── package.json
+```
+Add the following content to `vercel.json`:
+```json title="vercel.json"
+{
+  "buildCommand": "modern deploy",
+  "outputDirectory": ".vercel/output"
+}
+```
+Commit your project to git, select Framework Preset as `Other` on the Vercel platform and deploy.
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
+### Full Stack Project
+Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. These projects need to be deployed on **Vercel Functions**.
+In addition to configuring `vercel.json` in the same way as a [pure front-end project](#pure-front-end-project), there are two points to note for full-stack projects:
+1. Currently, Modern.js does not support deploying BFF projects on the Vercel platform. We will support it in future versions.
+2. When deploying on Vercel platform, the default node runtime is `20.x`, it is recommended to choose `18.x` when deploying full-stack projects,
+see [Serverless Function contains invalid runtime error](https://vercel.com/guides/serverless-function-contains-invalid-runtime-error), you can modify `package.json` to specify the version:
+```json title="package.json"
+"engines": {
+  "node": "18.x"
+}
+```
+### Monorepo
+:::info
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#pure-front-end-project-1) to deploy.
+:::
+For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
+We take a pnpm Monorepo repository as an example and deploy the Monorepo project on Vercel.
+Assuming the directory structure of the Monorepo repository is as follows:
+```
+.
+├── packages
+│   ├── app
+│   └── app-dep1
+├── package.json
+├── pnpm-lock.yaml
+└── pnpm-workspace.yaml
+```
+First, you need to configure the **Root Directory** as `packages/app` on the Vercel platform:
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-root-directory.png" />
+Specify Node.js runtime as `18.x`:
+```json title="package.json"
+"engines": {
+  "node": "18.x"
+}
+````
+Add the following script to `packages/app/package.json` to run `build` command of the other repositories in the workspace before run the `deploy` command for the `app` repository:
+```json
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy",
+  }
+}
+```
+Add the following content to the `packages/app/vercel.json` file:
+```json title="vercel.json"
+{
+  "buildCommand": "npm run deploy",
+  "outputDirectory": ".vercel/output"
+}
+```
+Just submit your code and deploy it using the Vercel platform.

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

@@ -455,8 +455,8 @@ export const init = (context: RuntimeContext) => {
 import { useRuntimeContext } from '@modern-js/runtime';
 export default () => {
-  const { context } = useRuntimeContext();
-  const { message } = context.getInitData();
+  const context = useRuntimeContext();
+  const { message } = context.initialData;
   return <div>{message}</div>;
 };

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

@@ -83,12 +83,6 @@ Modern.js supports the use of [styled-components](https://styled-components.com/
 If you need to use other CSS-in-JS solutions, you can integrate them into your project on your own.
-## Testing Framework
-Modern.js supports the use of [Jest](https://jestjs.io/) for unit testing or integration testing. This feature is optional. Please refer to ["Using Jest"](/en/guides/advanced-features/testing) to enable it.
-If you need to use [Vitest](https://vitest.dev/) or other testing frameworks, you can integrate them into your project on your own.
 ## UI Components
 Modern.js can be used with any React UI component library from the community, such as [MUI](https://mui.com/), [Ant Design](https://ant.design/), [Arco Design](https://github.com/arco-design/arco-design), [Semi Design](https://semi.design/), [Radix UI](https://www.radix-ui.com/), and more.

package/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx CHANGED Viewed

@@ -105,7 +105,7 @@ interface IAppContext {
   /** Information for server routes */
   serverRoutes: ServerRoute[];
   /** Tools type of the current project */
-  toolsType?: 'app-tools' | 'module-tools' | 'monorepo-tools';
+  toolsType?: 'app-tools' | 'module-tools';
   /** Type of the bundler being used */
   bundlerType?: 'webpack' | 'rspack' | 'esbuild';
 }

package/docs/en/guides/topic-detail/generator/create/option.md CHANGED Viewed

@@ -20,7 +20,6 @@ Options:
   -d,--debug               using debug mode to log something (default: false)
   --mwa                    create mwa application using default config (default: false)
   --module                 create module application using default config (default: false)
-  --monorepo               create monorepo application using default config (default: false)
   --generator <generator>  run custom generator
   -p, --plugin <plugin>    use generator plugin to create new solution or customize Modern.js solution (default: [])
   --dist-tag <distTag>     use specified tag version for it\'s generator (default: "")
@@ -89,10 +88,6 @@ Quickly create a Web App project.
 Quickly create a Npm Module project.
-## --monorepo
-Quickly create a Monorepo project.
 ## -p, --plugin \<plugin>
 Specify a generator plugin.

package/docs/en/guides/topic-detail/generator/create/use.mdx CHANGED Viewed

@@ -4,7 +4,7 @@ sidebar_position: 1
 # Usage
-Modern.js provides `@modern-js/create` tool for creating project templates provided by Modern.js, including [Web App](https://modernjs.dev/), [Npm Module](https://modernjs.dev/module-tools), [Monorepo](/guides/topic-detail/monorepo/intro.html).
+Modern.js provides `@modern-js/create` tool for creating project templates provided by Modern.js, including [Web App](https://modernjs.dev/), [Npm Module](https://modernjs.dev/module-tools).
 The following will introduce how to use `@modern-js/create`.
@@ -47,12 +47,3 @@ npx @modern-js/create@latest npm-module
 ? Please select the programming language: TS
 ? Please select the package manager: pnpm
 ```
-### Create Monorepo Project
-```bash
-npx @modern-js/create@latest monorepo
-? Please select the type of project you want to create: Monorepo
-? Please select the package manager: pnpm
-```

package/docs/en/guides/topic-detail/generator/new/config.md CHANGED Viewed

@@ -117,32 +117,3 @@ Options:
 - Enable Storybook -- storybook
 - Enable Runtime API -- runtime_api
-## Monorepo
-### sub_solution
-Question: Please select the type of project you want to create.
-Options:
-- Web App -- mwa
-- Npm Module -- module
-### packageName
-Question: Please fill in the project name
-:::info
-The value of the `name` field in the `package.json` file of the sub-project, which is a string type.
-:::
-### packagePath
-Question: Please fill in the sub-project directory name
-:::info
-The name of the subdirectory in the `apps` or `packages` directory on which the sub-project is based, which is a string type.
-:::

package/docs/en/guides/topic-detail/generator/new/use.md CHANGED Viewed

@@ -73,23 +73,3 @@ npm run new
 ```
 After running, Storybook plugin dependencies will be installed in the project, and the `storybook` command will be added. A `stories` directory will be created for Storybook module development, along with prompt information for registering Storybook plugins.
-## Monorepo
-Monorepo projects use the `new` command provided by `@modern-js/monorepo-tools`.
-The `new` command provides the ability to create sub-project.
-For example:
-Create Web App Sub-project:
-```bash
-? Please select the type of project you want to create: Web App
-? Please fill in the sub-project name: web_app
-? Please fill in the sub-project directory name: web_app
-? Please select the programming language: TS
-? Please select the bundler: webpack
-```
-After running, a sub-project named `web_app` will be created in the `apps` directory of the project. In the sub-project directory, you can still run the `new` command to create project elements and enable features.

package/docs/zh/apis/app/runtime/web-server/unstable_middleware.mdx CHANGED Viewed

@@ -11,7 +11,7 @@ title: Unstable Middleware
 ```ts title="server/index.ts"
 import { UnstableMiddleware } from '@modern-js/runtime/server';
-export const unstableMiddlewares: UnstableMiddleware = [];
+export const unstableMiddleware: UnstableMiddleware[] = [];
 ```
 ## 类型
@@ -73,7 +73,7 @@ const time: UnstableMiddleware = async (c, next) => {
   console.log(`${end - start}`);
 };
-export const unstableMiddlewares: UnstableMiddleware = [time];
+export const unstableMiddleware: UnstableMiddleware[] = [time];
 ```
 ### 注入服务端数据，供页面 dataLoader 消费
@@ -100,7 +100,7 @@ const setPayload: UnstableMiddleware = async (
   await next();
 };
-export const unstableMiddlewares: UnstableMiddleware = [setPayload];
+export const unstableMiddleware: UnstableMiddleware[] = [setPayload];
 ```
 ```ts title="src/routes/page.data.ts"
@@ -129,5 +129,31 @@ const auth: UnstableMiddleware = async (c, next) => {
   await next();
 };
-export const unstableMiddlewares: UnstableMiddleware = [auth];
+export const unstableMiddleware: UnstableMiddleware[] = [auth];
+```
+### 修改响应体
+```ts
+import { UnstableMiddleware } from '@modern-js/runtime/server';
+const modifier: UnstableMiddleware = async (c, next) => {
+  await next();
+  const { response } = c;
+  const text = await response.text();
+  const newText = text.replace('<html>', `<html lang="${language}">`);
+  const newheaders = response.headers;
+  newheaders.set('x-custom-value', 'modern');
+  c.response = c.body(newText, {
+    status: response.status,
+    headers: newheaders,
+  });
+};
+export const unstableMiddleware: UnstableMiddleware[] = [modifier];
 ```

package/docs/zh/guides/advanced-features/web-server.mdx CHANGED Viewed

@@ -108,7 +108,7 @@ export const middleware: Middleware = (context, next) => {
 **总的来说，CSR 项目中，使用 Hook 基本能满足简单场景的所有需求。SSR 项目中，可以使用 Middleware 做更复杂的 Node 扩展。**
-### UnstableMiddleware
+### Unstable Middleware
 Modern.js 将提供新 Middleware 为 Web Server 添加前置中间件，支持在处理页面的前后执行自定义逻辑。

package/docs/zh/guides/basic-features/data/data-fetch.mdx CHANGED Viewed

@@ -155,6 +155,8 @@ export async function loader() {
 ### 错误处理
+#### 基本用法
 在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 `loader` 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/guides/basic-features/routes#错误处理) 组件：
 ```tsx
@@ -182,6 +184,31 @@ const ErrorBoundary = () => {
 export default ErrorBoundary;
 ```
+#### 实践
+在 SSR 项目中你可以通过在 data loader 中 `throw response` 的方式，控制页面的状态码，展示对应的 UI，如以下示例，整条路由路线中有一个 loader
+throw response，页面的状态码将与这个 `response` 保持一致，页面的 UI 也会切换为 `ErrorBoundary`:
+```ts
+// routes/user/profile/page.data.ts
+export async function loader() {
+  const user = await fetchUser();
+  if(!user){
+    throw new Response('The user was not found', { status: 404 });
+  }
+  return user;
+}
+// routes/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as { data: string };
+  return <div className="error">{error.data}</div>;
+};
+export default ErrorBoundary;
+```
 ### 获取上层组件的数据
 很多场景下，子组件需要获取到祖先组件 `loader` 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
@@ -385,8 +412,6 @@ export const loader = () => {}
 ```
 ### 错误用法
 1. `loader` 中只能返回可序列化的数据，在 SSR 环境下，`loader` 函数的返回值会被序列化为 JSON 字符串，然后在客户端被反序列化为对象。因此，`loader` 函数中不能返回不可序列化的数据（如函数）。