@modern-js/main-doc 2.58.3 → 2.60.0

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

@@ -1,19 +1,20 @@
 ---
-title: Data writing
 sidebar_position: 4
 ---
 
-# Data writing
+# Data Writing
 
-In the Data Loader chapter, the way Modern.js fetch data is introduced. You may encounter two problems.：
-1. How to update the data in Data Loader？
-2. How to write new data to the server?
+In the [Data Fetching](/guides/basic-features/data/data-fetch) section, we introduced how Modern.js fetches data. This might bring up two questions:
 
-EdenX's solution for this is DataAction.
+1. How do I update the data returned by the Data Loader?
+2. How do I send new data to the server?
 
-## Basic Example
+In Modern.js, you can use Data Action to address these scenarios.
+
+## What is Data Action
+
+Modern.js recommends managing routes using [conventional routing](/guides/basic-features/routes). Each route component (`layout.ts`, `page.ts`, or `$.tsx`) can have a same-named `.data` file. These files can export an `action` function, known as Data Action, which developers can call at an appropriate time:
 
-Data Action, like Data Loader, is also based on convention routing. Through Modern.js's [nested routing](/guides/basic-features/routes#routing-file-convention), each routing component (`layout.ts`, `page.ts` or `$.tsx`) can have a `data` file with the same name, and a function named `action` can be exported in the `data` file.
 ```bash
 .
 └── routes
@@ -21,17 +22,21 @@ Data Action, like Data Loader, is also based on convention routing. Through Mode
         ├── layout.tsx
         └── layout.data.ts
 ```
-Define the following code in the file:
+
+You can export a Data Action function in the `routes/user/layout.data.ts` file:
+
 ```ts title="routes/user/layout.data.ts"
-import type { ActionFunction } from '@modern-js/runtime/router';
+import type { ActionFunction } from '@modern-js/runtime/router;
 
 export const action: ActionFunction = ({ request }) => {
-    const newUser = await request.json();
-    const name = newUser.name;
-    return updateUserProfile(name);
+  const newUser = await request.json();
+  const name = newUser.name;
+  return updateUserProfile(name);
 }
 ```
 
+In the route component, you can use `useFetcher` to get the corresponding `submit` function, which executes and triggers Data Action:
+
 ```tsx title="routes/user/layout.tsx"
 import {
   useFetcher,
@@ -64,44 +69,24 @@ export default () => {
 }
 ```
 
-Here, when the submit is executed, the defined action function will be triggered; in the action function, the submitted data can be obtained through request (request.json, request.formData, etc.), and the data can be obtained, and then the data can be sent to the server.
+After executing `submit`, the defined `action` function will be triggered. You can get the submitted data from the [parameters](/guides/basic-features/data/data-write.html#parameters) in the `action` function and ultimately send the data to the server.
 
-After the action function is executed, the loader function code will be executed and the corresponding data and views will be updated.
+Once the `action` function executes, Modern.js will automatically run the `loader` function code to update the data and view accordingly.
 
 ![action flow](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-flow.png)
 
+## `action` Function
 
+Similar to the `loader` function, the `action` function takes two parameters: `params` and `request`.
 
-## Why provide Data Action?
+### params
 
-Data Action is mainly provided in Modern.js to keep the state of the UI and the server in sync, which can reduce the burden of state management.
-
-The traditional state management method will hold the state on the client side and remotely respectively:：
-
-![traditional state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage.png)
-
-In Modern.js, we hope to help developers automatically synchronize the state of the client and server through Loader and Action:：
-
-![state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage1.png)
+`params` is the dynamic route segments when the route is a [dynamic route](/guides/basic-features/routes#dynamic-routes), which are passed as parameters to the `action` function:
 
-If the data shared by the components in the project are the state of the main server, there is no need to introduce a client state management library in the project, request data through Data Loader, through [`useRouteLoaderData`](/guides/basic-fe Atures/data/data-fetch.md) shares data in subcomponents,
-
-Modify and synchronize the state of the server through Data Action.
-
-
-
-## `action` function
-
-Like the `loader` function, the `action` function has two parameters, `params` and `request`:
-
-### `params`
-
-When the routing file passes through `[]`, it will be used as [dynamic routing](/guides/basic-features/routes#dynamic routing), and the dynamic routing fragment will be passed into the `action` function as a parameter:：
-
-```tsx
-// routes/user/[id]/page.data.ts
-import { ActionFunctionArgs } from '@modern-js/runtime/router';
+```tsx title="routes/user/[id]/page.data.ts"
+import { ActionFunctionArgs } from '@modern-js/runtime/router;
 
+// When visiting /user/123, the function parameter is `{ params: { id: '123' } }`
 export const action = async ({ params }: ActionFunctionArgs) => {
   const { id } = params;
   const res = await fetch(`https://api/user/${id}`);
@@ -109,17 +94,13 @@ export const action = async ({ params }: ActionFunctionArgs) => {
 };
 ```
 
-When accessing `/user/123`, the parameter of the `action` function is `{ params: { id: '123' } }`.
-
+### request
 
-### `request`
+`request` is an instance of [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
 
-Through `request`, you can fetch data submitted by the client in the action function, such as `request.json()`, `request.formData()`, `request.json()`, etc.
+Using `request`, you can retrieve data submitted from the client in the action function, such as `request.json()`, `request.formData()`, `request.json()`, etc. Refer to [Data Types](#data-types) for which API to use.
 
-For the specific API, please refer to [data type] (#data-type).
-
-```tsx
-// routes/user/[id]/page.data.ts
+```tsx title="routes/user/[id]/page.data.ts"
 import { ActionFunctionArgs } from '@modern-js/runtime/router';
 
 export const action = async ({ request }: ActionFunctionArgs) => {
@@ -130,18 +111,13 @@ export const action = async ({ request }: ActionFunctionArgs) => {
 
 ### Return Value
 
-The return value of the `action` function can be any serializable value or a [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance,
-
-The data in the response can be accessed through [`useActionData`](https://reactrouter.com/en/main/hooks/use-action-data).
+The return value of the `action` function can be any serializable content or a [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance. You can access the content via [`useActionData`](https://reactrouter.com/en/main/hooks/use-action-data).
 
+## useSubmit and useFetcher
 
-## useSubmit 和 useFetcher
+### Difference
 
-### Differences
-
-You can use [`useSubmit`](https://reactrouter.com/en/main/hooks/use-submit) or [`useFetcher`](https://reactrouter.com/en/main/hooks/use-fetcher) calls action, and the difference between them is through
-
-`useSubmit` calls action, which will trigger the browser's navigation, and `useFetcher` will not trigger the browser's navigation.
+You can call Data Action using [`useSubmit`](https://reactrouter.com/en/main/hooks/use-submit) or [`useFetcher`](https://reactrouter.com/en/main/hooks/use-fetcher). The difference is that `useSubmit` triggers browser navigation, while `useFetcher` does not.
 
 useSubmit:
 
@@ -151,29 +127,28 @@ submit(null, { method: "post", action: "/logout" });
 ```
 
 useFetcher:
+
 ```ts
 const { submit } = useFetcher();
 submit(null, { method: "post", action: "/logout" });
 ```
 
-The `submit` function has two input parameters, `method` and `action`. `method` is equivalent to `method` at the time of form submission. In most scenarios where data is written,the `method` can be passed into `post`.
-
-`action` is used to specify which routing component `action` is triggered. If the `action` parameter is not passed in, the action of the current routing component will be triggered by default, that is,
-the execution of submit in the `user/page.tsx` component or subcomponent will trigger the action defined in `user/page.data.ts`.
-
+The `submit` function takes two parameters. The first parameter is the `formData` passed to the server. The second parameter is an optional object where:
+- `method` corresponds to the form submission method. In most data writing scenarios, you can set the `method` to `post`.
+- `action` specifies the route component to trigger the Data Action. If not provided, it defaults to the current route component's action. For example, executing submit in `user/page.tsx` or its sub-components will trigger the action defined in `user/page.data.ts`.
 
 :::info
-For more information about these two APIs, please refer to the relevant documents：
-- [`useSubmit`](https://reactrouter.com/en/main/hooks/use-submit)
-- [`useFetcher`](https://reactrouter.com/en/main/hooks/use-fetcher)
 
-:::
+More information about the API can be found in the relevant documentation: [`useSubmit`](https://reactrouter.com/en/main/hooks/use-submit), [`useFetcher`](https://reactrouter.com/en/main/hooks/use-fetcher).
 
+:::
 
-### Type of data
+### Data Types
 
 The first parameter of the `submit` function can accept different types of values.
-Such as `FormData`：
+
+For example, `FormData`:
+
 ```ts
 let formData = new FormData();
 formData.append("cheese", "gouda");
@@ -181,7 +156,8 @@ submit(formData);
 // In the action, you can get the data by request.json
 ```
 
-Or the value of type `URLSearchParams`：
+or `URLSearchParams`:
+
 ```ts
 let searchParams = new URLSearchParams();
 searchParams.append("cheese", "gouda");
@@ -189,7 +165,8 @@ submit(searchParams);
 // In the action, you can get the data by request.json
 ```
 
-Or any acceptable value of the `URLSearchParams` constructor：
+or any value that the `URLSearchParams` constructor accepts:
+
 ```ts
 submit("cheese=gouda&toasted=yes");
 submit([
@@ -199,7 +176,7 @@ submit([
 // In the action, you can get the data by request.json
 ```
 
-By default, if the first parameter in the `submit` function is an object, the corresponding data will be encoded as `formData`：
+By default, if the first parameter of the `submit` function is an object, the corresponding data will be encoded as `formData`:
 
 ```ts
 submit(
@@ -213,7 +190,7 @@ submit(
 // In the action, you can get the data by request.formData
 ```
 
-it can also be specified as json encoding：
+You can also specify the encoding type via the second parameter:
 
 ```tsx
 submit(
@@ -229,13 +206,25 @@ submit('{"key":"value"}', {
 // In the action, you can get the data by request.json
 ```
 
-or submit plain text：
+or submit plain text:
+
 ```ts
 submit("value", { method: "post", encType: "text/plain" });
 // In the action, you can get the data by request.text
 ```
 
+## Why Data Action?
+
+Modern.js provides Data Action primarily to keep the UI and server state in sync, reducing the burden of state management. Traditional state management methods maintain state separately on the client and remote server:
+
+![traditional state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage.png)
+
+In Modern.js, we aim to help developers automatically synchronize client and server state using Loader and Action:
+
+![state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage1.png)
+
+If the shared data in your project mainly comes from the server, you don't need to introduce a client-side state management library. Use Data Loader to request data and share it in sub-components via [`useRouteLoaderData`](/guides/basic-features/data/data-fetch). Use Data Action to modify and synchronize the server's state.
 
-## CSR 和 SSR
+## CSR and SSR
 
-Like Data Loader, in the SSR project, Data Action is executed on the server (the framework will automatically send a request to trigger Data Action), while in the CSR project, Data Action is executed on the client.
+Similar to Data Loader, in SSR projects, Data Action is executed on the server (the framework automatically sends requests to trigger Data Action), while in CSR projects, Data Action is executed on the client.

package/docs/en/guides/basic-features/debug/_meta.json

@@ -0,0 +1 @@
+["mock", "proxy", "rsdoctor", "using-storybook"]

package/docs/en/guides/basic-features/debug/rsdoctor.mdx

@@ -0,0 +1,57 @@
+import { PackageManagerTabs } from '@theme';
+
+# Using Rsdoctor
+
+Rsdoctor is a build analysis tool that supports both Webpack and Rspack. In Modern.js, we recommend using Rsdoctor to diagnose and analyze the build process and build outputs.
+
+## Install Dependencies
+
+Depending on whether your project uses Rspack or Webpack, choose the corresponding plugin installation.
+
+### Rspack Plugin
+
+<PackageManagerTabs command="add @rsdoctor/rspack-plugin -D" />
+
+### Webpack Plugin
+
+<PackageManagerTabs command="add @rsdoctor/webpack-plugin -D" />
+
+## Register Plugin
+
+In `modern.config.ts`, you can register the Rspack or Webpack plugin via `tools.bundlerChain`. Refer to the example below:
+
+```ts title="modern.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  // ...
+  tools: {
+    rspack(config, { appendPlugins }) {
+      // Only register the plugin when RSDOCTOR is true, as the plugin will increase build time.
+      if (process.env.RSDOCTOR) {
+        appendPlugins(
+          new RsdoctorRspackPlugin({
+            // Plugin options
+          }),
+        );
+      }
+    },
+  },
+};
+```
+
+:::note
+The above code is an example of using Rspack. If you are using Webpack, please switch the plugin accordingly.
+:::
+
+## Execute Build
+
+You can execute the build command within your project. After the build is complete, Rsdoctor will automatically open the analysis page for the build.
+
+```bash
+RSDOCTOR=true npm run build
+```
+
+## Related Documentation
+
+For more information, please refer to the [Rsdoctor Website](https://rsdoctor.dev/).

package/docs/en/guides/{advanced-features → basic-features/debug}/using-storybook.mdx

@@ -228,3 +228,5 @@ export default config;
 The default config file path is `modern.config.(j|t)s`, for the detail config, see [modern.js config](/configure/app/usage).
 
 If the original project includes configurations for Babel, they need to be written in the modern configuration. Most Babel configurations have already been included in Modern.js.
+
+After installation, make the corresponding [configuration](/guides/basic-features/debug/using-storybook#configurations).

package/docs/en/guides/basic-features/render/_meta.json

@@ -0,0 +1 @@
+["ssr", "streaming-ssr", "ssr-cache", "ssg"]

package/docs/en/guides/basic-features/render/ssg.mdx

@@ -0,0 +1,208 @@
+---
+---
+
+# Static Site Generation
+
+SSG (Static Site Generation) is a technical solution that generates complete static web pages at build time based on data and templates. This means that in a production environment, pages are pre-rendered with content and can be cached by a CDN. SSG can offer better performance and higher security for pages that do not require dynamic data.
+
+## Enabling SSG
+
+First, we need to enable the SSG feature by running `pnpm run new`:
+
+```bash
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable SSG
+```
+
+After running the command, register the SSG plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { ssgPlugin } from '@modern-js/plugin-ssg';
+
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+  plugins: [..., ssgPlugin()],
+});
+```
+
+## Development Debugging
+
+Since SSG also renders pages in a Node.js environment, we can enable SSR during the **development phase** to expose code issues early and validate the SSG rendering effect:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  }
+}
+```
+
+## Using SSG in Conventional Routing
+
+In **conventional routing**, Modern.js generates routes based on the file structure under the entry point, allowing the framework to collect complete route information.
+
+### Basic Usage
+
+For example, the following is a project directory structure using conventional routing:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        ├── page.tsx
+        └── profile
+            └── page.tsx
+```
+
+The above file directory will generate the following three routes:
+
+- `/`
+- `/user`
+- `/user/profile`
+
+:::tip
+If you are not familiar with the rules of conventional routing, refer to the [Routing Solution](/guides/basic-features/routes) first.
+
+:::
+
+Add component code in `src/routes/page.tsx`:
+
+```jsx title="src/routes/page.tsx"
+export default () => {
+  return <div>Index Page</div>;
+};
+```
+
+Run the command `pnpm run dev` at the project root and check the `dist/` directory, where only one HTML file `main/index.html` is generated.
+
+Run the command `pnpm run build` at the project root, and after the build completes, check the `dist/` directory again. This time, you'll find `main/index.html`, `main/user/index.html`, and `main/user/profile/index.html` files, each corresponding to the routes listed above.
+
+Each route in **conventional routing** will generate a separate HTML file. Checking `main/index.html`, you will find it contains the text `Index Page`, which demonstrates the effect of SSG.
+
+After running `pnpm run serve` to start the project, inspect the returned document in the Network tab of the browser's development tools. The document includes the fully rendered content from the component.
+
+### Preventing Default Behavior
+
+By default, all routes in **conventional routing** have SSG enabled. Modern.js provides another field to prevent the default SSG behavior.
+
+For example, in the following directory structure, routes `/`, `/user`, and `/user/profile` all have SSG enabled:
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+You can disable the default behavior of certain routes by configuring `preventDefault`. After configuring as shown below, only the SSG pages for `/` and `/user/profile` will be generated:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      preventDefault: ['/user'],
+    },
+  },
+});
+```
+
+## Using SSG in Manual Routing
+
+**Manual routing** defines routes through component code, requiring the application to run to obtain accurate route information. Therefore, you cannot use the SSG feature out of the box. Developers need to configure which routes require SSG.
+
+For example, consider the following code with multiple routes. By setting `output.ssg` to `true`, it will only render the entry route (`/`) by default.
+
+import SelfRouteExample from '@site-docs/components/self-route-example';
+
+<SelfRouteExample />
+
+If you want to enable SSG for `/about` as well, you can configure `output.ssg`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+After running `pnpm run build`, you will see a new `main/about/index.html` file in the `dist/` directory.
+
+After running `pnpm run serve` to start the project, inspect the returned document in the Network tab of the browser's development tools. The document includes the fully rendered content from the component.
+
+:::info
+The above example introduces single-entry scenarios. For more information, refer to the [API Documentation](/configure/app/output/ssg).
+:::
+
+## Adding Route Parameters
+
+In Modern.js, some routes can be dynamic, such as `/user/:id` in manual routing or `/user/[id]/page.tsx` in conventional routing.
+
+ can configure specific parameters in `output.ssg` to render routes with specified parameters. For example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        {
+          url: '/user/:id',
+          params: [{
+            id: 'modernjs',
+          }],
+        },
+      ],
+    },
+  },
+});
+```
+
+Here, the `/user/modernjs` route will be rendered, and the `id` parameter will be passed to the component during rendering. When multiple values are configured, multiple pages will be generated.
+
+:::note
+The combination of dynamic routing and SSG is very useful for generating static pages in real-time based on data changes from a CMS system.
+:::
+
+## Configuring Request Headers for Rendering
+
+Modern.js supports configuring request headers for specific entries or routes. For example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      headers: {
+        "x-tt-env": "ppe_modernjs"
+      },
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {
+            "from": "modern-website"
+          },
+        },
+      ],
+    },
+  },
+});
+```
+
+In the above configuration, the `x-tt-env` request header is set for all routes, and the `from` request header is specifically set for the `/about` route.
+
+:::tip
+Headers set in routes will override headers set for entries.
+:::