@modern-js/main-doc 2.0.0-beta.3 → 2.0.0-beta.5

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

@@ -0,0 +1,86 @@
+---
+sidebar_position: 5
+---
+
+# CSS Modules
+
+Modern.js out of the box support for [CSS Modules](https://github.com/css-modules/css-modules).
+
+## File Suffix Form CSS Modules
+
+By default, files ending in `.module.(css|scss|sass|less)` are treated as CSS Modules files, for example:
+
+```css title="button.module.css"
+.redColor {
+  color: red;
+}
+```
+
+```js title="Button.jsx"
+import styles from './button.module.css';
+
+export default function Button() {
+  return (
+    <button type="button" className={styles.redColor}>
+      red button
+    </button>
+  );
+}
+```
+
+Will eventually be compiled as:
+
+```js
+<button type="button" className="button_redColor__1-RBg">
+  red button
+</button>;
+```
+
+## Global CSS Modules
+
+If you want to remove the `.module` suffix from the filename, you can set [`output.disable CssModuleExtension`](/docs/configure/app/output/disable-css-module-extension).
+
+After setting, all style files except the style files in the `node_modules/` directory and the file name format of `[name].global.(css|scss|sass|less)` will be processed as CSS Modules.
+
+If you need global styles at this point, you can solve it by creating a style file with the filename format `[name].global.(css|scss|sass|less)`, for example:
+
+```css title="app.global.css"
+.bg-blue {
+  background-color: blue;
+}
+```
+
+```css title="button.css"
+.redColor {
+  color: red;
+}
+```
+
+```js title="App.jsx"
+import './app.global.css';
+import styles from './button.css';
+
+export default function Button() {
+  return (
+    <button type="button" className={`${styles.redColor} bg-blue`}>
+      button
+    </button>
+  );
+}
+```
+
+Will eventually be compiled as:
+
+```js
+<button type="button" className="button__redColor--JsFYl bg-blue">
+  button
+</button>;
+```
+
+The final effect is as follows:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/more-css-modules.png)
+
+:::tip
+When using [babel-plugin-react-css-modules](https://github.com/gajus/babel-plugin-react-css-modules), it is important to note that the configuration option `generateScopedName` of this plugin needs to be the same as [`output.css ModuleLocalIdentName`](/docs/configure/app/output/css-module-local-ident-name).
+:::

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/css/less-sass.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 4
+---
+
+# Less and Sass
+
+[Less](https://lesscss.org/) and [Sass](https://sass-lang.com/) are two commonly used CSS preprocessors that Modern.js built-in support for the Less and Sass compile capabilities.
+
+## Customized Configuration
+
+- If you need to customize the configuration of [less-loader](https://github.com/webpack-contrib/less-loader), please refer to the [tools.less](/docs/configure/app/tools/less).
+- If you need to customize the configuration of [sass-loader](https://github.com/webpack-contrib/sass-loader), please refer to the [tools.less](/docs/configure/app/tools/sass).
+
+
+::: Tips
+CSS files pre-compiled by Less and Sass will still undergo Modern.js build-in [PostCSS](https://postcss.org/) conversion, which has good browser compatibility. For related content, please refer to [[PostCSS](/docs/guides/basic-features/css/postcss)].
+:::

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

@@ -0,0 +1,81 @@
+---
+sidebar_position: 3
+---
+
+# PostCSS
+
+[PostCSS](https://postcss.org/) is a tool for converting CSS code with JavaScript tools and plugins. Modern.js built-in PostCSS and integrates common PostCSS plugins such as [Autoprefixer](https://github.com/postcss/autoprefixer) to meet the style development needs of most projects.
+
+By default, Modern.js compile and transform CSS as follows:
+
+1. [Autoprefixer](https://github.com/postcss/autoprefixer) Automatically add the required browser vendor prefix to CSS rules according to the required browser range. Modern.js default supported browser ranges are: `['> 0.01%', 'not dead', 'not op_mini all']`.
+
+  :::info Note
+    - [Supported browser range: `> 0.01%`] means that the browser market share is greater than 0.01%.
+    - `Not dead` means excluding browsers that are no longer officially supported and browsers that have not been updated in the past 24 months.
+    - `not op_mini all` means exclude Opera Mini.
+  :::
+
+
+  :::info Additional
+    If you need to modify the default browser support range, you can configure `browserslist` in the project's `package.json` file, and set the rule to refer to the use of [Browserslist](https://github.com/browserslist/browserslist). The following is an example:
+    ```json title ="package.json"
+    {
+      "Browserslist": [
+        "The last 1 versions",
+        "> 1%",
+        "IE 10"
+      ]
+    }
+    ```
+  :::
+
+2. Provide [CSS custom properties](https://www.w3.org/TR/css-variables-1/) support, you can define and use custom variables in CSS, such as:
+
+  ```css
+  :root {
+    --main-bg-color: pink;
+  }
+
+  body {
+    background-color: var(--main-bg-color);
+  }
+  ```
+3. Provide [CSS Nesting](https://drafts.csswg.org/css-nesting-1/) support, you can use nested writing in CSS, such as:
+
+  ```css
+  table.colortable td {
+    text-align: center;
+  }
+  table.colortable td.c {
+    text-transform: uppercase;
+  }
+  ```
+  It can also be rewritten as CSS nested:
+  ```css
+  table.colortable {
+    & td {
+      text-align: center;
+      &.c { text-transform: uppercase }
+    }
+  }
+  ```
+
+4. Fix known [Flexbugs](https://github.com/philipwalton/flexbugs).
+5. Provide compatibility with the following CSS features:
+    - [`initial` attribute value](https://developer.mozilla.org/en-US/docs/Web/CSS/initial_value)
+    - [`break-` attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
+    - [`font-variant`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
+    - [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#syntax_improvements_in_level_4)
+
+  When you need to modify the PostCSS configuration, you can implement it through the underlying configuration [`tools.postcss`](/docs/configure/app/tools/postcss), here is an example:
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  tools: {
+    postcss: {
+      plugins: ['autoprefixer', ('postcss-flexbugs-fixes': {})],
+    },
+  },
+});
+```

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

@@ -0,0 +1,95 @@
+---
+sidebar_position: 2
+---
+
+# Tailwind CSS
+
+
+
+[Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles. To use [Tailwind CSS](https://tailwindcss.com/) in the Modern.js, just execute `pnpm run new` in the project root directory and turn it on.
+
+Choose as follows:
+
+```bash
+? Action: Enable features
+? Enable features: Enable Tailwind CSS
+```
+
+When using, add the following code to the root component of the entry (such as `src/App.jsx`):
+
+```js
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+```
+
+You can then use the Utility Class provided by Tailwind CSS in each component.
+
+::: info Additional
+According to different needs, you can optionally import the CSS files provided by Tailwind CSS. Since the use of `@taiwind` is equivalent to directly importing CSS files, you can refer to the content in the annotate in the [`@tailwind` usage](https://tailwindcss.com/docs/functions-and-directives#tailwind) document for the purpose of the CSS files provided by Tailwind CSS.
+:::
+
+When you need to customize the [theme](https://tailwindcss.com/docs/theme) configuration of Tailwind CSS, you can modify it in the configuration [`source.designSystem`](/docs/configure/app/source/design-system), for example, add a color theme `primary`:
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  source: {
+    designSystem: {
+      extend: {
+        colors: {
+          primary: '#5c6ac4',
+        },
+      },
+    },
+  },
+});
+```
+
+When you need special configuration for Tailwind CSS other than [theme](https://tailwindcss.com/docs/theme), you can configure it in [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss), for example setting `variants`:
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  tools: {
+    tailwindcss: {
+      variants: {
+        extend: {
+          backgroundColor: ['active'],
+        },
+      },
+    },
+  },
+});
+```
+
+## Use the [`Twin`](https://github.com/ben-rogerson/twin.macro)
+
+In the previous chapter, we introduced what CSS-in-JS is and the CSS-in-JS library [styled-components](https://styled-components.com/) commonly used by the community. This section will explain how to use [Tailwind CSS](https://tailwindcss.com/) in CSS with [`Twin`](https://github.com/ben-rogerson/twin.macro). Using [`Twin`](https://github.com/ben-rogerson/twin.macro) makes it easier to use Tailwind CSS in CSS-in-JS code. [`Twin`](https://github.com/ben-rogerson/twin.macro) for its own description is:
+
+> *Twin blends the magic of Tailwind with the flexibility of css-in-js*
+
+After enabling the "Tailwind CSS" function, you first need to install the ['Twin'](https://github.com/ben-rogerson/twin.macro) dependency:
+
+``` bash
+pnpm add twin.macro -D
+```
+
+When the project installs the `twin.macro` dependency, Modern.js detects the dependency and adds twin.macro related configuration to the `baby-plugin-macro` of build-in. So after installing the dependency, there is no need for manual configuration. Here is an example of a simple use of twin.macro:
+
+``` js
+import tw from 'twin.macro'
+
+const Input = tw.input`border hover:border-black`
+```
+
+:::tip
+If a `MacroError: /project/App.tsx` error occurs during runtime, it may be caused by a lack of `twin.macro` dependency.
+:::
+
+For more usage, please refer to the [twin.macro](https://github.com/ben-rogerson/twin.macro/blob/master/docs/index.md).
+
+`twin.macro` reads the `tailwindcss.config.js` files in the project directory by default, or reads the Tailwind CSS configuration via the file path specified by [twin.config](https://github.com/ben-rogerson/twin.macro/blob/master/docs/options.md#options) on the `babel-plugin-macro`. However, these additional configurations are not required in the Modern.js.
+
+When the Tailwind CSS is configured in the `modern.config.ts` file by [`source.designSystem`](/docs/configure/app/source/design-system) and [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss), these configurations will also take effect on the `twin.macro`.
+
+> When configuring Tailwind CSS for a project, the combination of the two configurations [`source.designSystem`](/docs/configure/app/source/design-system) and [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) is equivalent to a separate configuration `tailwindcss.config.js` file.
+> Where [`source.designSystem`](/docs/configure/app/source/design-system) is equivalent to the [`theme`](https://v2.tailwindcss.com/docs/configuration#theme) configuration of Tailwind CSS.

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

@@ -0,0 +1,66 @@
+---
+title: Fetch Data
+sidebar_position: 3
+---
+
+Modern.js provides out of the box fetching data capabilities, developers can use these APIs to develop in CSR and SSR environments isomorphic.
+
+It should be noted that these APIs do not help applications to initiate requests, but help developers better manage the relationship between data and routing.
+
+## useLoader(Old)
+
+**`useLoader`** is an API in Modern.js old version. The API is a React Hook specially provided for SSR applications, allowing developers to fetch data in components.
+
+:::tip
+CSR don't need to use `useLoader` to fetch data.
+:::
+
+Here is the simplest example:
+
+```tsx
+import { useLoader } from '@modern-js/runtime';
+
+export default () => {
+  const { data } = useLoader(async () => {
+    console.log('fetch in useLoader');
+
+    // No real request is sent here, just a hard coding data is returned.
+    // In a real project, the data obtained from the remote end should be returned.
+    return {
+      name: 'modern.js',
+    };
+  });
+
+  return <div>Hello, {data?.name}</div>;
+};
+```
+
+After the above code starts, visit the page. You can see that the log is printed at terminal, but not at console in browser.
+
+This is because Modern.js server-side rendering, the data returned by the `useLoader` is collected and injected into the HTML of the response. If SSR rendering succeeds, the following code snippet can be seen in the HTML:
+
+```html
+<script>
+window._SSR_DATA = {};
+</script>
+```
+
+In this global variable, every piece of data is recorded, and this data will be used first in the process of rendering on the browser side. If the data does not exist, the `useLoader` function will be re-executed.
+
+:::note
+During the build phase, Modern.js will automatically generate a Loader ID for each `useLoader` and inject it into the JS bundle of SSR and CSR, which is used to associate Loader and data.
+:::
+
+Compared with `getServerSideProps` in the Next.js, get data in advance before rendering. Using `useLoader`, you can get the data required by the local UI in the component without passing the data layer by layer. Similarly, it will not add redundant logic to the outermost data acquisition function because different routes require different data requests. Of course, `useLoader` also has some problems, such as the difficulty of Treeshaking server-level code, and the need for one more pre-render at the server level.
+
+Modern.js in the new version, a new Loader solution is designed. The new solution solves these problems and can cooperate with **nested routing** to optimize page performance.
+
+:::note
+Detailed APIs can be found at [useLoader](/docs/apis/app/runtime/core/use-loader).
+:::
+
+## Route Loader
+
+:::note
+Stay tuned.
+:::

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,
+  }
+})
+```