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

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.0.0-beta.3 build /github/workspace/packages/toolkit/main-doc
+> @modern-js/main-doc@2.0.0-beta.4 build /github/workspace/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/inspect.md

@@ -33,7 +33,3 @@ modern inspect --env production
 ### SSR Configuration
 
 If the project has SSR enable, an additional `webpack.ssr.inspect.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
-
-### Modern Configuration
-
-if project enable [enableModernMode](/docs/configure/app/output/enable-modern-mode), an additional `webpack.modern.inspect.js` file will be generated in the `dist/`corresponding to the webpack configuration at modern web build.

package/en/docusaurus-plugin-content-docs/current/components/init-app.md

@@ -0,0 +1,42 @@
+Modern.js generator will provide an interactive Q & A interface, initialization items according to the result, according to the default selection:
+
+```bash
+? Please select the solution you want to create: MWA Solution
+? Development Language: TS
+? Package Management Tool: pnpm
+```
+
+After create the project, Modern.js automatically installs dependency and creates a git repository.
+
+```bash
+[INFO] dependencies are automatically installed
+[INFO] git repository has been automatically created
+[INFO] Success！
+You can run the following command in the directory of the new project：
+pnpm run dev          # Run and debug the project according to the requirements of the development environment
+pnpm run build        # Build the project according to the requirements of the product environment
+pnpm run start        # Run the project according to the requirements of the product environment
+pnpm run lint         # Check and fix all codes
+pnpm run new          # Create more project elements, such as application portals
+```
+
+:::note
+In addition to working during project initialization, the Modern.js generator can also generate modules of the project in subsequent development, which is not thrown away as soon as it is used.
+:::
+
+Now, the project structure is as follows:
+
+```
+.
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```

package/en/docusaurus-plugin-content-docs/current/configure/app/server/routes.md

@@ -52,16 +52,14 @@ After executing the `dev` command, you can see in `dist/route.json` that there a
       "entryName": "page-a",
       "entryPath": "html/page-a/index.html",
       "isSPA": true,
-      "isSSR": false,
-      "enableModernMode": false
+      "isSSR": false
     },
     {
       "urlPath": "/b",
       "entryName": "page-a",
       "entryPath": "html/page-a/index.html",
       "isSPA": true,
-      "isSSR": false,
-      "enableModernMode": false
+      "isSSR": false
     },
   ]
 }

package/en/docusaurus-plugin-content-docs/current/configure/app/tools/esbuild.md

@@ -3,59 +3,36 @@ title: tools.esbuild
 sidebar_label: esbuild
 ---
 
-* Type: `Object`
-* Default: `undefined`
+- Type: `Object`
+- Default: `undefined`
 
 ## Introduction
 
-Esbuild is a JavaScript Bundler/Minifier written in Go language, which is characterized by extremely fast speed. In terms of code compression, esbuild has dozens of times the performance improvement compared to webpack's built-in terser compressor.
-
-Modern.js provides the ability to compile and compress code based on esbuild. After opening it in a large project, ** can greatly reduce the time required for code compression, while effectively avoiding OOM (heap out of memory) problems **.
-
-Although the use of esbuild compression has brought about an improvement in construction efficiency, the compression ratio of esbuild is lower than that of terser, so the size of the ** bundle will increase **, please use it according to the business situation (more suitable for middle and back-end scenarios).
-
-For a detailed comparison between compression tools, see [mining-benchmarks](https://github.com/privatenumber/minification-benchmarks).
-
-:::info
-In addition to code compression, esbuild can also replace babel for code compilation. The advantage is that it can improve the compilation speed, but the disadvantage is that it cannot use the rich babel plug-in capabilities.
+:::tip About esbuild
+[esbuild](https://esbuild.github.io/) is a front-end build tool based on Golang. It has the functions of bundling, compiling and minimizing JavaScript code. Compared with traditional tools, the performance is significantly improved. When minimizing code, compared to webpack's built-in terser minimizer, esbuild has dozens of times better performance.
 :::
 
-## Configuration
-
-### target
+Modern.js provides esbuild plugin that allow you to use esbuild instead of babel-loader, ts-loader and terser for transformation and minification process.
 
-* Type: `string | string[]`
-* Default `'esnext'`
-
-Set the target environment for the generated JavaScript and CSS code.
-
-Can be set directly to the JavaScript language version, such as `es5`, `es6`, `es2020`. It can also be set to several target environments, each target environment is an environment name followed by a version number. For example: `['chrome58', 'edge16', 'firefox57']`.
-
-The following environments are supported:
+## Configuration
 
-- chrome
-- edge
-- firefox
-- ie
-- ios
-- node
-- opera
-- safari
+You can set the esbuild compilation behavior through the `tools.esbuild` config.
 
-By default, ES6 code, such as template string, is introduced into the esbuild compression process. If you need to be ES5 compatible, you can set `target` to `es5`.
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
 
-```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     esbuild: {
-      target: 'es5',
+      loader: {
+        target: 'chrome61',
+      },
+      minimize: {
+        target: 'chrome61',
+      },
     },
   },
 });
 ```
 
-:::info
-When setting `target` to `es5`, you need to ensure that all code is escaped to es5 code by babel, otherwise it will cause an esbuild compilation error: `Transforming 'xxx' to the configured target environment ("es5") is not supported yet`.
-
-A detailed description of the `target` field can be found in [esbuild-target](https://esbuild.github.io/api/#target).
-:::
+For config details, please refer to [Modern.js Builder - esbuild Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-esbuild.html#config).

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

@@ -0,0 +1,38 @@
+---
+sidebar_position: 1
+---
+
+# CSS-in-JS
+
+CSS-in-JS is a technology that can write CSS styles in JS files. Modern.js integrates the CSS-in-JS  library [styled-components](https://styled-components.com/) commonly used in the community, which uses the new feature of JavaScript [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write CSS styles for components. You can use the [styled-components](https://styled-components.com/) API directly from `@modern-js/runtime/styled`.
+
+When you need to write a `div` component with an internal font in red, you can do the following implementation:
+
+```js
+import styled from '@modern-js/runtime/styled'
+
+const RedDiv = styled.div`
+  color: red;
+`
+```
+
+When you need to dynamically set the component style according to the `props` of the component, for example, when the attribute `primary` of `props` is `true`, the color of the button is white, and otherwise it is red. The implementation code is as follows:
+
+```js
+import styled from '@modern-js/runtime/styled'
+
+const Button = styled.button`
+  color: ${props => props.primary ? "white" : "red"};
+  font-size: 1em;
+`
+```
+
+For more usage of styled-components, please refer to [[styled-components official website](https://styled-components.com/) ].
+
+:::info Additional
+Modern.js uses the Babel plugin [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) internally, and the plugin can be configured through [`tools.styled Components`](/docs/configure/app/tools/styled-components).
+:::
+
+:::tip
+If you need to use [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/) and other CSS-in-JS libraries, you need to install the dependency of the corresponding library first. For specific usage, please refer to the official website of the corresponding library.
+:::

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.
+:::