@modern-js/main-doc 2.0.0-beta.2 → 2.0.0-beta.4

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/routes.md

@@ -0,0 +1,270 @@
+---
+title: Routes
+sidebar_position: 1
+---
+
+Modern.js build-in provides partial support for [React Router 6](https://reactrouter.com/en/main) and provides various types of routing modes. According to different [entry](/docs/guides/concept/entries) types, routing is divided into three modes, namely **Conventional routing**, **Self-controlled routing** and **Other**.
+
+:::note
+The routes mentioned in this section are client routes, that is, SPA routes.
+:::
+
+## Conventional routing
+
+With `routes/` as the agreed entry, Modern.js will automatically generate the corresponding routing structure based on the file system.
+
+Modern.js supports the popular convention routing mode in the industry: **nested routing**. When using nested routing, the routing of the page corresponds the UI structure, and we will introduce this routing mode in detail.
+
+
+```
+/user/johnny/profile                  /user/johnny/posts
++------------------+                  +-----------------+
+| User             |                  | User            |
+| +--------------+ |                  | +-------------+ |
+| | Profile      | |  +------------>  | | Posts       | |
+| |              | |                  | |             | |
+| +--------------+ |                  | +-------------+ |
++------------------+                  +-----------------+
+```
+
+### Routing file convention
+
+There are two file conventions in the `routes/` directory `layout.[jt]sx` and `page.[jt]sx`(abbreviated as `.tsx` later). These two files determine the layout hierarchy of the application, where `layout.tsx` is used as the layout component, and `page.tsx` is used as the content component, which is the leaf node of the entire routing table.
+
+For example, here `routes/layout.tsx` will be used as the layout component of all components under the `/` route:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+When the route is `/`, there will be the following UI layout:
+
+```tsx
+<Layout>
+  <Page />
+</Layout>
+```
+
+Similarly, `routes/user/layout.tsx` will be used as a layout component for all components under the `/user` route. When the route is `/user`, the following UI layout will be available:
+
+```tsx
+<Layout>
+  <UserLayout>
+    <UserPage>
+  <UserLayout>
+</Layout>
+```
+
+#### Layout
+
+`<Layout>` component refers to all `layout.tsx` files in the `routes/` directory, which represent the layout of the corresponding route segment, and use `<Outlet>` to represent sub-components.
+
+:::note
+`<Outlet>` is a new API in React Router 6, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet) for details.
+:::
+
+In order to facilitate the introduction of the relationship between `<Layout>` and `<Outlet>`, the following file directory example:
+
+```bash
+.
+└── routes
+    ├── blog
+    │   └── page.tsx
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+1. When the route is `/`, `<Outlet>` in `routes/layout.tsx` represents the component exported in `routes/page.tsx`, generating the following UI structure:
+
+```tsx
+<Layout>
+  <Page />
+</Layout>
+```
+
+2. When the route is `/blog`, `<Outlet>` in `routes/layout.tsx` represents the component exported in `routes/blog/page.tsx`, generating the following UI structure:
+
+```tsx
+<Layout>
+  <BlogPage />
+</Layout>
+```
+
+3. When the route is `/user`, `<Outlet>` in `routes/layout.tsx` represents the component exported in `routes/user/layout.tsx`. `<Outlet>` in `routes/user/layout.tsx` represents the component exported in `routes/user/page.tsx`. Generate the following UI structure:
+
+```tsx
+<Layout>
+  <UserLayout>
+    <UserPage>
+  <UserLayout>
+</Layout>
+```
+
+In summary, if there is a `layout.tsx` in the file directory of the subroute, the `<Outlet>` in the previous `layout.tsx` is the `layout.tsx` under the file directory of the subroute, otherwise it is the `page.tsx` under the file directory of the subroute.
+
+#### Page
+
+All routes should end with the `<Page>` component. In the `page.tsx` file, if the developer introduces the `<Outlet>` component, it will have no effect.
+
+### Dynamic routing
+
+With a file directory named `[]`, the generated route will be used as a dynamic route. For example the following file directory:
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+The `routes/[id]/page.tsx` file is converted to the `/:id` route. Except for the `/blog` route that exactly matches, all other `/xxx` will match this route.
+
+In component, you can get the corresponding named parameters through [useParams](/docs/apis/app/runtime/router/#useparams).
+
+### Layout with No Path
+
+When a directory name begins with `__`, the corresponding directory name is not converted to the actual routing path, such as the following file directory:
+
+```
+.
+└── routes
+    ├── __auth
+    │   ├── layout.tsx
+    │   ├── login
+    │   │   └── page.tsx
+    │   └── signup
+    │       └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+Modern.js will generate two routes, `/login` and `/sign`, `__auth/layout.tsx` component will be used as the layout component of `login/page.tsx` and `signup/page.tsx`, but __auth will not be used as the route path fragment.
+
+
+This feature is useful when you need to do separate layouts for certain types of routes, or when you want to categorize routes.
+
+### No Layout
+
+In some cases, the project needs more sophisticated routes, but these routes do not have independent UI layouts. If you create a route like a normal file directory, the directory level will be deeper.
+
+Therefore Modern.js supports splitting routing fragments by `.` instead of file directory. For example, when you need `/user/profile/2022/edit`, you can directly create the following file:
+
+```
+└── routes
+    ├── user.profile.[id].edit
+    │      └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+When accessing a route, you will get the following UI layout:
+
+```tsx
+<RootLayout>
+   <UserProfileEdit />   // routes/user.profile.[id].edit/page.tsx
+</RootLayout>
+```
+
+### Loading
+
+In each layer directory under `routes/`, developers can create `loading.tsx` files and export a `<Loading>` component by default.
+
+When the component exists in the routing directory, all routing switches under this level of subrouting will use the `<Loading>` component as the Fallback UI when JS Chunk is loaded. When the `layout.tsx` file is not defined in this directory, the `<Loading>` component will not take effect. For example, the following file directory:
+
+```bash
+.
+└── routes
+    ├── blog
+    │   ├── [id]
+    │   │   └── page.tsx
+    │   └── page.tsx
+    ├── layout.tsx
+    ├── loading.tsx
+    └── page.tsx
+```
+
+When a route jumps from `/` to `/blog`, if the JS Chunk of the `<Blog>` component is not loaded, the component UI exported in `loading.tsx` will be displayed first. But when jumping from `/blog` to `/blog/20220101`, it will not be displayed.
+
+### ErrorBoundary
+
+In each layer directory under `routes/`, the developer can also define a `error.tsx` file, and export a `<ErrorBoundary>` component by default.
+
+When the component exists in a routing directory, the component render error is caught by the `ErrorBoundary` component. The `<ErrorBoundary>` component does not take effect when the directory does not have a `layout.tsx` file defined.
+
+`<ErrorBoundary>` can return the UI view when the error occurred. When the `<ErrorBoundary>` component is not declared at the current level, the error will bubble up to the higher component until it is caught or throws an error. At the same time, when a component fails, it will only affect the routed component and sub-component that caught the error. The state and view of other components are not affected and can continue to interact.
+
+<!-- Todo API 路由-->
+Within the `<ErrorBoundary>` component, you can use [useRouteError](/docs/apis/app/runtime/router/#useparams) to get the specific information of the error:
+
+```tsx
+import { useRouteError } from '@modern-js/runtime/router';
+export default const ErrorBoundary = () => {
+  const error = useRouteError();
+  return (
+    <div>
+        <h1>{error.status}</h1>
+        <h2>{error.message}</h2>
+    </div>
+  )
+}
+```
+
+## 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:
+
+```tsx
+import { Route, Routes, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+export default () => {
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+:::note
+Under self-controlled routing, if developers want to use the [Loader API](https://reactrouter.com/en/main/hooks/use-loader-data#useloaderdata) capabilities in React Router 6 in SSR will be relatively complicated, it is recommended to use conventional routing directly. Modern.js has already encapsulated everything for you.
+<!-- Todo 嵌套路由带来的优化可以补充下文档-->
+If the project only wants to upgrade to React Router 6 and does not want to use the optimizations brought by nested routing, then [useLoader](/docs/apis/app/runtime/core/use-loader) will still work under SSR.
+:::
+
+## Other
+
+By default, Modern.js turn on the built-in routing scheme, React Router.
+
+```js
+export default defineConfig({
+  runtime: {
+    router: true,
+  }
+})
+```
+
+Modern.js exposes the React Router API from the `@modern-js/runtime/router` namespace for developers to use, ensuring that developers and Modern.js use the same code. In addition, in this case, the React Router code will be packaged into JS products. If the project already has its own routing scheme, or does not need to use client routing, this feature can be turned off.
+
+```js
+export default defineConfig({
+  runtime: {
+    router: false,
+  }
+})
+```

package/en/docusaurus-plugin-content-docs/current/guides/concept/entries.md

@@ -0,0 +1,116 @@
+---
+title: Entries
+sidebar_position: 2
+---
+
+Entries are Modern.js default file convention, and each entry in the project is a separate page, corresponding to a server level route.
+
+Many configurations, such as HTML templates, Meta information, whether SSR is enabled, SSG, server level routing rules are divided by the entry dimension.
+
+## Single Entry and Multiple Entries
+
+Modern.js initialization project is a single entry, the project structure is as follows:
+
+```
+.
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── package.json
+├── modern.config.ts
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```
+
+Modern.js can easily switch from single entry to multiple entry. You can execute `pnpm run new` under the project to create entry through generator:
+
+```bash
+? Action: Create project element
+? Create project element: New "entry"
+? Entry name: new-entry
+```
+
+After execution, the `src/` directory will become the following structure:
+
+```
+.
+├── modern-app-env.d.ts
+├── myapp
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── new-entry
+    └── routes
+        ├── index.css
+        ├── layout.tsx
+        └── page.tsx
+```
+
+The original code was moved to the directory with the same name as the `name` in the `package.json`, and a new directory was created.
+
+After executing `pnpm run dev`, you can see that a `/new-entry` route has been added, and the migrated code route has not changed.
+
+:::note
+Modern.js will use the directory with the same name as the `name` in the `package.json` as the main entry, the default route is `/`, and the default route for other entries is `/{entryName}`.
+:::
+
+## Entry conditions
+
+By default, the Modern.js entry currently scans the file under `src/`, identifies the entry, and generates the corresponding server level route.
+
+:::tip
+You can change the entry directory to another directory by [source.entriesDir](/docs/configure/app/source/entries-dir).
+:::
+
+Not all first-level directories under `src/` will become project entrances. The directory where the entry is located must meet one of the following four conditions:
+
+
+1. Directory with `routes/`
+2. Has the `App.[jt]sx?` file
+3. With `index.[jt]sx?` file
+2. With `pages/` directory (compatible Modern.js 1.0)
+
+When the `src/` directory satisfies the entry feature, the Modern.js considers the current project to be a single entry application.
+
+:::tip
+Single entry The default entry name is `main`.
+:::
+
+When the project is not a single-entry application, Modern.js further look at the first-level directory under `src/`.
+
+## Difference between entries
+
+Entries to different conventions have different behaviors.
+
+### routes
+
+If the entry is the `routes/` convention, Modern.js will scan the files under `routes` at startup, and automatically generate the client route based on the file convention(react-router).
+
+For details, please refer to [Routing](/docs/guides/basic-features/routes).
+
+### App
+
+If the entry is the `App.[jt]sx?` convention, the developer can freely set the client route in this file, or not set the client route.
+
+For details, please refer to [Routing](/docs/guides/basic-features/routes).
+
+### Index
+
+Typically, the above two modes are sufficient, but when developers need to take over the React mount logic themselves, or take over the Webpack entry entirely, the `index.[jt]sx?`convention can be used.
+
+If the entry is the `index.[jt]sx?` convention, the Modern.js determines the build behavior based on whether the file has a default component export.
+
+For details, please refer to [customized App](/docs/guides/advanced-features/custom-app).
+
+## configuration
+
+In Modern.js, you can manually configure the entry in `modern.config.[jt]s`, in addition to using the file convention to generate the entry.
+
+:::tip
+Details can be found in [source.entries](/docs/configure/app/source/entries).
+:::

package/en/docusaurus-plugin-content-docs/current/guides/concept/lifecycle.md

@@ -0,0 +1,15 @@
+---
+title: Lifecycle
+sidebar_position: 1
+---
+
+Modern.js application has a complete lifecycle, including CLI, Server Side and Runtime three stages.
+
+Modern.js lifecycle is as follows:
+
+
+:::note
+The rectangle of the pink box represents the plugin hook provided by the Modern.js, and the light yellow base color ellipse represents the linkage point with the next stage.
+:::
+
+![lifecycle](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/life-cycle.svg)

package/en/docusaurus-plugin-content-docs/current/guides/get-started/quick-start.md

@@ -0,0 +1,162 @@
+---
+title: Quick Start
+sidebar_position: 1
+---
+
+## Environment
+
+### Node.js
+
+Requires [Node.js LTS](https://github.com/nodejs/Release) and ensures that the Node version is greater than or equal to 14.19.0, 16.x version is recommended.
+
+Modern.js recommend installing [nvm](https://github.com/nvm-sh/nvm#install--update-script) in the development environment and integrating [script to automatically switch node versions](https://github.com/nvm-sh/nvm#deeper-shell-integration) in the shell.
+
+Then there is a `.nvmrc` file with the content of `lts/fermium` or `lts/gallium` in the root directory of the repository, it will automatically install or switch to the correct Node.js version when entering the repository.
+
+### pnpm
+
+[pnpm](https://pnpm.io/installation) is recommended for package management.
+
+```bash
+npm install -g pnpm
+```
+
+:::note
+Modern.js also supports package management with `yarn` and `npm`.
+:::
+
+## Installation
+
+Modern.js provides the `@modern-js/create` tool to create projects. Don't install globally, use `npx` to run on demand.
+
+Projects can be created using an existing empty directory:
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+
+Projects can also be created directly from the new directory:
+
+```bash
+npx @modern-js/create myapp
+```
+
+## Initialize
+
+import InitApp from '@site-docs/components/init-app.md'
+
+<InitApp />
+
+## Development
+
+Execute `pnpm run dev` in the project to start the project:
+
+```bash
+$ pnpm run dev
+
+> modern dev
+
+info    Starting dev server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.58.87:8080/
+  > Network:  http://10.254.68.105:8080/
+
+ Client ✔ done in 76.10ms
+```
+
+Open `http://localhost:8000/` in your browser and you will see the following:
+
+![dev](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/dev.png)
+
+## Configuration
+
+The `modern.config.ts` files exist in Modern.js projects created by the generator.
+
+Features can be enabled through the configuration file, or the default behavior of the coverage Modern.js. For example, add the following configuration to enable SSR:
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+});
+```
+
+Re-execute `pnpm run dev`, in the browser Network menu, you can find that the project has completed page rendering at the server level.
+
+## Build
+
+Execute `pnpm run build` in the project to build the project production environment product:
+
+```bash
+$ pnpm run build
+
+> modern build
+
+info    Create a production build...
+
+info    File sizes after production build:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-corejs.ffeb7fb8.js     214.96 kB    67.23 kB
+  dist/static/js/lib-react.09721b5c.js      152.61 kB    49.02 kB
+  dist/static/js/218.102e2f39.js            85.45 kB     28.5 kB
+  dist/static/js/lib-babel.a7bba875.js      11.93 kB     3.95 kB
+  dist/html/main/index.html                 5.84 kB      2.57 kB
+  dist/static/js/main.3568a38e.js           3.57 kB      1.44 kB
+  dist/static/css/async/304.c3c481a5.css    2.62 kB      874 B
+  dist/asset-manifest.json                  1.48 kB      349 B
+  dist/static/js/async/304.c45706bc.js      1.4 kB       575 B
+  dist/static/js/async/509.fcb06e14.js      283 B        230 B
+
+ Client ✔ done in 3.57s
+ ```
+
+The bundle is generated to `dist/` by default, and the directory structure is as follows:
+
+```
+.
+├── asset-manifest.json
+├── html
+│   └── main
+├── loader-routes
+│   └── main
+├── modern.config.json
+├── route.json
+└── static
+    ├── css
+    └── js
+```
+
+## Verify
+
+Execute `pnpm run start` in the project to verify locally that the bundle is running correctly:
+
+```bash
+$ pnpm run start
+
+> modern start
+
+Starting the modern server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.58.87:8080/
+  > Network:  http://10.254.68.105:8080/
+```
+
+Open http://localhost:8000/ in the browser and the content should be the same as when `pnpm run dev`.
+
+## Deploy
+
+After the local verification is completed, the products under `dist/` can be organized into the structure required by the server for deployment.

package/en/docusaurus-plugin-content-docs/current/guides/get-started/upgrade.md

@@ -0,0 +1,78 @@
+---
+title: Upgrade
+sidebar_position: 2
+---
+
+## Upgrade with command
+
+Modern.js provides the `upgrade` command to support projects to upgrade to the latest  version.
+
+Execute `pnpm run upgrade` in the project:
+
+```bash
+$ pnpm run upgrade
+
+> modern upgrade
+
+[INFO] [Project Type]: Application
+[INFO] [Modern.js Latest Version]: 2.0.0
+[INFO] Upgrade Modern.js package version success!
+```
+
+You can see that the dependency in the project `package.json` has been changed to the latest.
+
+## Specify version upgrade
+
+Modern.js all packages are published using the **unified version number**.
+
+According to the website Release Note, developers can also manually upgrade the project to the desired version.
+
+:::tip
+When upgrading, you need to upgrade to all packages provided by the Modern.js, rather than upgrading a single dependency.
+:::
+
+## lock child dependency
+
+When there is a problem with one of the child dependencies of the project, and the Modern.js cannot be updated immediately, you can use the package manager to lock the child dependency version.
+
+### pnpm
+
+For projects using pnpm, add the following configuration to the `package.json` in the **project root directory** and re-execute `pnpm install`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "package-name": "^1.0.0"
+    }
+  }
+}
+```
+
+### Yarn
+
+For projects using Yarn, add the following configuration to the `package.json` in the **project root directory** and re-execute `yarn install`:
+
+```json
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+### Npm
+
+For projects using Npm, add the following configuration to the `package.json` in the **project root directory** and re-execute `npm install`:
+
+```json
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+For Monorepo repositories, the dependency version can only be locked in the `package.json` in the project root directory, and all packages in Monorepo are affected.
+:::

package/{zh/tutorials/first-app → en/docusaurus-plugin-content-docs/current/guides}/overview.md

@@ -2,10 +2,10 @@
 sidebar_position: 0
 ---
 
-# 概览
+# Overview
 
 import OverviewNav from '@site/src/components/OverviewNav';
-import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json'
-import Link from '@docusaurus/Link';
 
-<OverviewNav cards={sidebarData.docsSidebars.tutorialsSidebar[1].items}/>
+import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
+
+<OverviewNav cards={sidebarData.docsSidebars.guidesSidebar} />

package/en/docusaurus-plugin-content-docs/current/tutorials/foundations/introduction.md

@@ -40,4 +40,4 @@ It mainly contains the following features:
 
 If you are a front-end beginner, you may find these concepts a bit complicated. We provide some [JavaScript and React](/docs/tutorials/foundations/basic) learning materials, you can do some understanding of them first。
 
-If you are an experienced developer and want to know how to use Modern.js, you can try [Create your first app](/docs/tutorials/first-app/overview), or read [Guide](/docs/guides/overview).
+If you are an experienced developer and want to know how to use Modern.js, you can try [Create your first app](/docs/tutorials/first-app/c01-start), or read [Guide](/docs/guides/overview).