@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -0,0 +1,352 @@
+---
+title: Routes
+sidebar_position: 1
+---
+# Routes
+
+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](/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](/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>
+```
+
+### (WIP)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](/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>
+  )
+}
+```
+
+### Hooks before rendering
+
+In some scenarios where you need to do some operations before the application renders, you can define `init` hooks in `routes/layout.tsx`. `init` will be executed on both the client and server side, the basic usage example is as follows:
+
+```ts title="src/routes/layout.tsx"
+import type { RuntimeContext } from '@modern-js/runtime';
+
+export const init = (context: RuntimeContext) => {
+  // do something
+};
+```
+
+The `init` hook allows you to mount some global data and access the `runtimeContext` variable from elsewhere in the application:
+
+:::note
+This feature is useful when the application requires pre-page data, custom data injection or framework migration (e.g. Next.js)
+
+:::
+
+```ts title="src/routes/layout.tsx"
+import {
+  RuntimeContext,
+} from '@modern-js/runtime';
+
+export const init = (context: RuntimeContext) => {
+  return {
+    message: 'Hello World',
+  }
+}
+```
+
+```tsx title="src/routes/page.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export default () => {
+  const { context } = useRuntimeContext();
+  const { message } = context.getInitData();
+
+  return <div>{message}</div>;
+}
+```
+
+When working with SSR, the browser side can get the data returned by `init` during SSR, and the developer can decide whether to retrieve the data on the browser side to overwrite the SSR data, for example:
+
+```tsx title="src/routes/layout.tsx"
+import {
+  RuntimeContext,
+} from '@modern-js/runtime';
+
+export const init = (context: RuntimeContext) => {
+  if (process.env.JUPITER_TARGET === 'node') {
+    return {
+      message: 'Hello World By Server',
+    }
+  } else {
+    const { context } = runtimeContext;
+    const data = context.getInitData();
+    // 如果没有获取到期望的数据
+    if (!data.message) {
+      return {
+        message: 'Hello World By Client'
+      }
+    }
+  }
+}
+```
+
+### Runtime Configuration
+
+In each root `Layout` component (`routes/layout.ts`), the application runtime configuration can be dynamically defined:
+
+```ts title="src/routes/layout.tsx"
+import type { AppConfig } from '@modern-js/runtime';
+
+export const config = (): AppConfig => {
+  return {
+    router: {
+      supportHtml5History: false
+    }
+  }
+};
+```
+
+## 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:
+
+```ts title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
+
+:::note
+Modern.js has a series of resource loading and rendering optimizations to the default convention-based routing, and provides out-of-the-box SSR capabilities,  when using self-directed routing, need to be packaged by the developer, and it is recommended that developers use convention-based routing.
+
+:::
+
+## 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/guides/concept/entries.mdx

@@ -0,0 +1,120 @@
+---
+title: Entries
+sidebar_position: 2
+---
+# Entries
+
+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](/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
+4. 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](/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](/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](/guides/concept/entries#自定义-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](/configure/app/source/entries).
+
+:::

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

@@ -0,0 +1,162 @@
+---
+title: Quick Start
+sidebar_position: 1
+---
+# Quick Start
+
+## 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-en/components/init-app"
+
+<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://192.168.0.1: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 serve` in the project to verify locally that the bundle is running correctly:
+
+```bash
+$ pnpm run serve
+
+> modern serve
+
+Starting the modern server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1: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.