@modern-js/main-doc 2.35.1 → 2.36.0

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

@@ -0,0 +1,241 @@
+---
+title: Data writing
+sidebar_position: 4
+---
+
+# 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?
+
+EdenX's solution for this is DataAction.
+
+## Basic Example
+
+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
+    └── user
+        ├── layout.tsx
+        └── layout.data.ts
+```
+Define the following code in the file:
+```ts title="routes/user/layout.data.ts"
+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);
+}
+```
+
+```tsx title="routes/user/layout.tsx"
+import {
+  useFetcher,
+  useLoaderData,
+  useParams,
+  Outlet
+} from '@modern-js/runtime/router';
+
+export default () => {
+  const userInfo = useLoaderData();
+  const { submit } = useFetcher();
+  const editUser = () => {
+    const newUser = {
+      name: 'Modern.js'
+    }
+    return submit(newUser, {
+      method: 'post',
+      encType: 'application/json',
+    })
+  }
+  return (
+    <div>
+      <button onClick={editUser}>edit user</button>
+      <div className="user-profile">
+        {userInfo}
+      </div>
+      <Outlet context={userInfo}></Outlet>
+    </div>
+  )
+}
+```
+
+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 the action function is executed, the loader function code will be executed and the corresponding data and views will be updated.
+
+![action flow](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-flow.png)
+
+
+
+## Why provide Data Action?
+
+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)
+
+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';
+
+export const action = async ({ params }: ActionFunctionArgs) => {
+  const { id } = params;
+  const res = await fetch(`https://api/user/${id}`);
+  return res.json();
+};
+```
+
+When accessing `/user/123`, the parameter of the `action` function is `{ params: { id: '123' } }`.
+
+
+### `request`
+
+Through `request`, you can fetch data submitted by the client in the action function, such as `request.json()`, `request.formData()`, `request.json()`, etc.
+
+For the specific API, please refer to [data type] (#data-type).
+
+```tsx
+// routes/user/[id]/page.data.ts
+import { ActionFunctionArgs } from '@modern-js/runtime/router';
+
+export const action = async ({ request }: ActionFunctionArgs) => {
+  const newUser = await request.json();
+  return updateUser(newUser);
+};
+```
+
+### 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).
+
+
+## useSubmit 和 useFetcher
+
+### 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.
+
+useSubmit:
+
+```ts
+const submit = useSubmit();
+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`.
+
+
+:::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)
+
+:::
+
+
+### Type of data
+
+The first parameter of the `submit` function can accept different types of values.
+Such as `FormData`：
+```ts
+let formData = new FormData();
+formData.append("cheese", "gouda");
+submit(formData);
+// In the action, you can get the data by request.json
+```
+
+Or the value of type `URLSearchParams`：
+```ts
+let searchParams = new URLSearchParams();
+searchParams.append("cheese", "gouda");
+submit(searchParams);
+// In the action, you can get the data by request.json
+```
+
+Or any acceptable value of the `URLSearchParams` constructor：
+```ts
+submit("cheese=gouda&toasted=yes");
+submit([
+  ["cheese", "gouda"],
+  ["toasted", "yes"],
+]);
+// 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`：
+
+```ts
+submit(
+  { key: "value" },
+  {
+    method: "post",
+    encType: "application/x-www-form-urlencoded",
+  }
+);
+
+// In the action, you can get the data by request.formData
+```
+
+it can also be specified as json encoding：
+
+```tsx
+submit(
+  { key: "value" },
+  { method: "post", encType: "application/json" }
+);
+
+submit('{"key":"value"}', {
+  method: "post",
+  encType: "application/json",
+});
+
+// In the action, you can get the data by request.json
+```
+
+or submit plain text：
+```ts
+submit("value", { method: "post", encType: "text/plain" });
+// In the action, you can get the data by request.text
+```
+
+
+## CSR 和 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.

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

@@ -161,7 +161,7 @@ These properties as defined are available via the [`useMatches`](https://reactro
 
 ```ts title="routes/layout.ts"
 export default () => {
-  const matches = useMatches;
+  const matches = useMatches();
   const breadcrumbs = matches.map(
     matchedRoute => matchedRoute?.handle?.breadcrumbName,
   );
@@ -186,7 +186,7 @@ The `routes/[id]/page.tsx` file will be converted to the `/:id` route. Except fo
 
 In the component, you can use [useParams](/apis/app/runtime/router/router#useparams) to get the corresponding named parameter.
 
-In the loader, params will be passed as the input parameter of the [loader function](/guides/basic-features/data-fetch#loader-function), and you can get the parameter value through `params.xxx`.
+In the loader, params will be passed as the input parameter of the [loader function](/guides/basic-features/data/data-fetch#loader-function), and you can get the parameter value through `params.xxx`.
 
 ### Dynamic Optional Routing
 
@@ -206,7 +206,7 @@ The `routes/user/[id$]/page.tsx` file will be converted to the `/user/:id?` rout
 
 In the component, you can use [useParams](/apis/app/runtime/router/router#useparams) to get the corresponding named parameter.
 
-In the loader, params will be passed as the input parameter of the [loader function](/guides/basic-features/data-fetch#loader-function), and you can get the parameter value through `params.xxx`.
+In the loader, params will be passed as the input parameter of the [loader function](/guides/basic-features/data/data-fetch#loader-function), and you can get the parameter value through `params.xxx`.
 
 ### Catch-all Routing
 
@@ -351,12 +351,12 @@ Similarly, when the route jumps from `/` or `/blog` to `/blog/123`, if the JS Ch
 
 ### Redirect
 
-You can use a [Data Loader](/guides/basic-features/data-fetch) file to redirect a route. For example, if you have a `routes/user/page.tsx` file and want to redirect the corresponding route, you can create a `routes/user/page.loader.ts` file:
+You can use a [Data Loader](/guides/basic-features/data/data-fetch) file to redirect a route. For example, if you have a `routes/user/page.tsx` file and want to redirect the corresponding route, you can create a `routes/user/page.data.ts` file:
 
-```ts title="routes/user/page.loader.ts"
+```ts title="routes/user/page.data.ts"
 import { redirect } from '@modern-js/runtime/router';
 
-export default () => {
+export const loader = () => {
   const user = await getUser();
   if (!user) {
     return redirect('/login');
@@ -502,7 +502,7 @@ To further improve the user experience and reduce loading time, Modern.js suppor
 :::info
 
 - This feature is currently only supported in Webpack projects and not yet supported in Rspack projects.
-- Preloading data currently only preloads the data returned by the [Data Loader](/guides/basic-features/data-fetch) in SSR projects.
+- Preloading data currently only preloads the data returned by the [Data Loader](/guides/basic-features/data/data-fetch) in SSR projects.
 
 :::
 

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

@@ -32,7 +32,7 @@ The project initialized by Modern.js is a single entry (SPA) project, with the f
 
 In a Modern.js project, you can easily switch from single entry to multiple entries by running `pnpm run new` in the project directory and creating an entry:
 
-```bash
+```text
 ? Please select the operation you want: Create Element
 ? Please select the type of element to create: New "entry"
 ? Please fill in the entry name: new-entry
@@ -56,7 +56,7 @@ After running the command, Modern.js will automatically generate a new entry dir
 
 The original entry code has been moved to a directory with the same name as the `name` field in `package.json`, and a `new-entry` entry directory has been created.
 
-After running `pnpm run dev`, you can see a new route named `/new-entry` has been added, and the migrated code route has not changed.
+You can run `pnpm run dev` to start the development server. At this point, you will see a new route named `/new-entry` added, and the existing page routes remain unchanged.
 
 :::tip
 Modern.js will use the entry with the same name as the `name` field in `package.json` as the main entry. The route of the main entry is `/`, and the route of other entries is `/{entryName}`.
@@ -76,7 +76,9 @@ import EntryMode from '@site-docs-en/components/entry-mode.mdx';
 By default, Modern.js scans the files under `src/` before starting the project, identifies the entry, and generates the corresponding server-side route.
 
 :::tip
-You can modify the directory for entry identification by using the [source.entriesDir](/configure/app/source/entries-dir) config.
+
+- You can custom the recognition directory for page entries by using [source.entriesDir](/configure/app/source/entries-dir).
+- If you need to customize the entry points, please refer to [Custom Entries](#custom-entries).
 
 :::
 
@@ -98,7 +100,7 @@ When the project is not a single entry application, Modern.js will further look
 
 ### Framework Mode Entry
 
-Framework mode refers to the need to use Modern.js framework capabilities, such as Router, SSR, integrated calls, etc. Under this type of entry convention, the entry defined by the developer is not a real webpack compilation entry. Modern.js will generate a wrapped entry during startup, and you can find the real entry in `node_modules/.modern/{entryName}/index.js`.
+The framework mode refers to the need to use the framework capabilities of Modern.js, such as nested routing, SSR, and integrated BFF, etc. Under this kind of entry convention, the entry defined by the developer is not the actual compilation entry. When Modern.js is launched, it generates a wrapped entry, and the real entry can be found at `node_modules/.modern/[entryName]/index.js`.
 
 #### Conventional Routing
 
@@ -146,7 +148,7 @@ export default (App: React.ComponentType, bootstrap: () => void) => {
   // do something before bootstrap...
   initSomething().then(() => {
     bootstrap();
-  })
+  });
 };
 ```
 
@@ -181,9 +183,11 @@ export default AppWrapper;
 
 ### Build Mode Entry
 
-Build mode refers to not using any Modern.js runtime capabilities and completely defining the project's webpack entry by the developer.
+Build mode refers to the mode where the entry point of the page is not automatically generated by Modern.js, but is fully defined by the developers themselves.
+
+When there is an `index.[jt]sx` file in the entry directory and it is not exported as a function using `export default`, this type of file will be recognized as the entry module for webpack or Rspack.
 
-If there is an `index.[jt]sx` file in the entry and it does not export a default function, then this file is the real webpack entry file. Similar to [Create React App](https://github.com/facebook/create-react-app), you need to mount the component to the DOM node by yourself, add hot update code, etc. For example:
+In this case, Modern.js will not generate the entry code automatically. Therefore, you need to manually mount the component to the DOM node, for example:
 
 ```js title=src/index.jsx
 import React from 'react';
@@ -193,42 +197,39 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-Modern.js **does not recommend** using this method for new projects, as it loses some of the framework's capabilities, such as the `runtime` configuration in the `modern.config.js` file will no longer take effect. However, this method can be very useful when migrating projects from other frameworks to Modern.js, such as CRA, or manually building webpack.
+This approach is equivalent to enabling the [source.entries.disableMount](/configure/app/source/entries) option in Modern.js. When you use this approach, **you will not be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the modern.config.js file will no longer take effect.
 
-## Specifying Entry Using Configuration
+## Custom Entries
 
-Most existing projects are not built according to the directory structure of Modern.js. If you want to change to the directory structure of Modern.js, there will be certain migration costs.
+In some cases, you may need to customize the entry configuration instead of using the entry conventions provided by Modern.js.
 
-In this case, in addition to using file conventions to generate entries, you can manually configure the entry in `modern.config.[jt]s`.
+For example, if you want to migrate a non-Modern.js project to Modern.js and it is not structured according to Modern.js directory structure, there might be some migration costs involved in changing it to the conventional structure. In such cases, you can custom the entries.
 
-```ts title="modern.config.ts"
-export default defineConfig({
-  source: {
-    entries: {
-      // Specify a new entry named entry_customize
-      entry_customize: './src/home/test/index.ts',
-    },
-    // Disable default ingress scanning
-    disableDefaultEntries: true,
-  },
-});
-```
+Modern.js provides the following configuration options that you can set in [modern.config.ts](/configure/app/usage):
 
-### Disable Default Entry Scanning
+- [source.entries](/configure/app/source/entries): Used to set custom entry objects.
+- [source.disableDefaultEntries](/configure/app/source/disable-default-entries): Used to disable Modern.js's default entry scanning behavior. When you use custom entries, parts of your project structure might coincidentally match the Modern.js conventional directory structure, but you may not want Modern.js to generate entry configurations for them. Enabling this option can help avoid this issue.
 
-When using custom entries, part of the project structure may coincidentally hit the directory conventions of Modern.js, but in fact, this part of the directory is not the real entry.
+### Example
 
-Modern.js provides the `disableDefaultEntries` configuration to disable the default entry scanning rules. When you need to customize the entry, you generally need to use `disableDefaultEntries` in combination with `entries`. This way, some existing projects can be quickly migrated without modifying the directory structure.
+Here is an example of a custom entry point. You can also refer to the documentation of the corresponding configuration options for more usage.
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   source: {
+    entries: {
+      // Specify an entry named 'my-entry'
+      'my-entry': {
+        // Path to the entry module
+        entry: './src/my-page/index.tsx',
+        // Disable automatic generation of entry code by Modern.js
+        disableMount: true,
+      },
+    },
+    // Disable entry scanning behavior
     disableDefaultEntries: true,
   },
 });
 ```
 
-:::tip
-For detailed usage, please refer to [source.entries](/configure/app/source/entries) and [source.disableDefaultEntries](/configure/app/source/disable-default-entries).
-
-:::
+Note that when you enable `disableMount`, **you won't be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the modern.config.ts file.

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

@@ -92,7 +92,7 @@ $ pnpm run build
 > modern build
 
 info    Staring production build...
-ready   Client compiled in 50ms
+ready   Client compiled in 50 ms
 info    Production file sizes:
 
   File                                      Size         Gzipped

package/docs/en/guides/topic-detail/framework-plugin/extend.mdx

@@ -1,5 +1,4 @@
 ---
-title: Extending
 sidebar_position: 5
 ---
 

package/docs/en/guides/topic-detail/framework-plugin/hook-list.mdx

@@ -1,5 +1,4 @@
 ---
-title: Hook List
 sidebar_position: 8
 ---
 

package/docs/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -1,7 +1,7 @@
 ---
-title: Hook Model
 sidebar_position: 2
 ---
+
 # Hook Model
 
 First, let's introduce some content about the basic plugin system in Modern.js, including the working mode of the Hook model, the operating mode of each Hook model, and the working mode of the Manager.

package/docs/en/guides/topic-detail/framework-plugin/implement.mdx

@@ -1,9 +1,8 @@
 ---
-title: Develop Plugins
 sidebar_position: 3
 ---
 
-# How to Develop Plugins
+# Develop Plugins
 
 The previous section introduced the Hook models used by Modern.js plugins, while this section describes how to develop plugins.
 

package/docs/en/guides/topic-detail/framework-plugin/introduction.mdx

@@ -1,7 +1,7 @@
 ---
-title: Introduction
 sidebar_position: 1
 ---
+
 # Introduction
 
 ## Modern.js Plugin System

package/docs/en/guides/topic-detail/framework-plugin/lifecycle.mdx

@@ -1,7 +1,7 @@
 ---
-title: Lifecycle
 sidebar_position: 1
 ---
+
 # Lifecycle
 
 Modern.js application has a complete lifecycle, including CLI, Server Side and Runtime three stages.

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

@@ -1,5 +1,4 @@
 ---
-title: Plugin API
 sidebar_position: 6
 ---
 
@@ -79,26 +78,43 @@ Used to retrieve the runtime context of the application.
 const useAppContext: () => IAppContext;
 
 interface IAppContext {
+  /** Root directory of the current project */
   appDirectory: string;
+  /** Source code directory */
+  srcDirectory: string;
+  /** Directory for output files */
+  distDirectory: string;
+  /** Directory for shared modules */
+  sharedDirectory: string;
+  /** Directory for framework temp files */
+  internalDirectory: string;
+  /** node_modules directory */
+  nodeModulesDirectory: string;
+  /** Path to the configuration file */
   configFile: string | false;
+  /** IPv4 address of the current machine */
   ip?: string;
+  /** Port number of the development server */
   port?: number;
-  distDirectory: string;
+  /** Name of the current project's package.json */
   packageName: string;
-  srcDirectory: string;
-  sharedDirectory: string;
-  nodeModulesDirectory: string;
-  internalDirectory: string;
-  plugins: {
-    cli?: any;
-    server?: any;
-  }[];
+  /** Currently registered plugins */
+  plugins: any[];
+  /** Information for entry points */
   entrypoints: Entrypoint[];
+  /** Information for server routes */
   serverRoutes: ServerRoute[];
-  htmlTemplates: HtmlTemplates;
+  /** Tools type of the current project */
+  toolsType?: 'app-tools' | 'module-tools' | 'monorepo-tools';
+  /** Type of the bundler being used */
+  bundlerType?: 'webpack' | 'rspack' | 'esbuild';
 }
 ```
 
+:::tip
+Some fields in the AppContext are dynamically set and will change as the program runs. Therefore, when plugins read these fields at different times, they may get different values.
+:::
+
 ### useHookRunners
 
 Used to retrieve the executor of Hooks and trigger the execution of specific Hooks.
@@ -116,3 +132,7 @@ export const myPlugin = (): CliPlugin => ({
   },
 });
 ```
+
+:::tip
+Please avoid executing the built-in hooks, as it may break the internal execution logic of the framework.
+:::

package/docs/en/guides/topic-detail/framework-plugin/relationship.mdx

@@ -1,8 +1,8 @@
 ---
-title: Relationship
 sidebar_position: 4
 ---
-# Relationship between Plugins
+
+# Relationship
 
 The plugin configuration object in Modern.js provides a series of fields to control plugin order, mutual exclusion, and other capabilities. The available fields are as follows:
 

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

@@ -129,13 +129,8 @@ Question: Please select the type of project you want to create.
 Options:
 
 - Web App -- mwa
-
-- Web App (Test)-- mwa_test
-
 - Npm Module -- module
 
-- Npm Module (Inner) -- inner_module
-
 ### packageName
 
 Question: Please fill in the project name

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

@@ -44,12 +44,12 @@ defineConfig(App, {
         return [
           {
             name: 'Table',
-            entry: 'http://localhost:8001',
+            entry: 'http://localhost:8081',
             // activeWhen: '/table'
           },
           {
             name: 'Dashboard',
-            entry: 'http://localhost:8002',
+            entry: 'http://localhost:8082',
             // activeWhen: '/dashboard'
           },
         ];

package/docs/en/tutorials/first-app/c05-loader.mdx

@@ -18,7 +18,7 @@ pnpm add faker@5
 pnpm add @types/faker@5 -D
 ```
 
-Create `src/routes/page.loader.ts`:
+Create `src/routes/page.data.ts`:
 
 ```tsx
 import { name, internet } from 'faker';
@@ -32,7 +32,7 @@ type LoaderData = {
   }[];
 };
 
-export default async (): Promise<LoaderData> => {
+export const loader = async (): Promise<LoaderData> => {
   const data = new Array(20).fill(0).map(() => {
     const firstName = name.firstName();
     return {

package/docs/en/tutorials/first-app/c06-model.mdx

@@ -195,9 +195,9 @@ const Item = ({
 export default Item;
 ```
 
-Next, we add `src/routes.page.loader` and modify `src/routes/page.tsx` to pass more parameters to the `<Item>` component:
+Next, we add `src/routes.page.data` and modify `src/routes/page.tsx` to pass more parameters to the `<Item>` component:
 
-```tsx title="src/routes/page.loader.ts"
+```tsx title="src/routes/page.data.ts"
 export type LoaderData = {
   code: number;
   data: {
@@ -207,7 +207,7 @@ export type LoaderData = {
   }[];
 };
 
-export default async (): Promise<LoaderData> => {
+export const loader = async (): Promise<LoaderData> => {
   const data = new Array(20).fill(0).map(() => {
     const firstName = name.firstName();
     return {
@@ -233,7 +233,7 @@ import { List } from 'antd';
 import { name, internet } from 'faker';
 import Item from '../components/Item';
 import contacts from '../models/contacts';
-import type { LoaderData } from './page.loader';
+import type { LoaderData } from './page.data';
 
 function Index() {
   const { data } = useLoaderData() as LoaderData;