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

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

@@ -4,7 +4,7 @@ sidebar_label: tsLoader
 ---
 
 :::info BUILDER
-This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.tsLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tsloader)。
+This configuration is Modern.js Builder configuration, more detail can see [tools.tsLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tsloader)。
 :::
 
 import Main from '@modern-js/builder-doc/en/config/tools/tsLoader.md'

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

@@ -4,7 +4,7 @@ sidebar_label: webpackChain
 ---
 
 :::info BUILDER
-This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.webpackChain](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpackchain)。
+This configuration is Modern.js Builder configuration, more detail can see [tools.webpackChain](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpackchain)。
 :::
 
 import Main from '@modern-js/builder-doc/en/config/tools/webpackChain.md'

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

@@ -4,7 +4,7 @@ sidebar_label: webpack
 ---
 
 :::info BUILDER
-This configuration is Modern.js Builder configuration, there may be links that cannot be redirected. for details, please refer to [tools.webpack](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpack)。
+This configuration is Modern.js Builder configuration, more detail can see [tools.webpack](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpack)。
 :::
 
 import Main from '@modern-js/builder-doc/en/config/tools/webpack.md'

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

@@ -0,0 +1,46 @@
+---
+title: Builder
+sidebar_position: 2
+---
+
+**Modern.js uses [Modern.js Builder](https://modernjs.dev/builder) to build your Web APP. **
+
+Modern.js Builder is one of the core components of Modern.js. It is a build engine for modern Web development and can be used independently of Modern.js. Modern.js Builder supports multiple bundlers such as webpack and rspack, and it uses webpack by default.
+
+## Build Architecture
+
+From the perspective of building, Modern.js is divided into three layers, from top to bottom:
+
+- Upper-layer framework: Modern.js.
+- Universal build engine: Modern.js Builder.
+- Low-level bundlers: webpack and rspack.
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
+
+## Builder Documentation
+
+Since Modern.js Builder is a module that can be used independently, we provide a separate document for it, the site address is: [modernjs.dev/builder](https://modernjs.dev/builder).
+
+In this document, you can learn about the detailed introduction of Modern.js Builder, and you can also find a complete usage guide for each building features. When you encounter building issues, it is recommended that you first read the Modern.js Builder documentation to solve them.
+
+## Builder Config
+
+The config of Modern.js is inherited from Modern.js Builder, so you can use all build configs provided by Modern.js Builder in Modern.js.
+
+Take the `html.title` config of Modern.js Builder as an example, you can directly use this config in the `modern.config.ts` file, and it will be automatically passed to Modern.js Builder.
+
+```ts title="modern.config.js"
+export default defineConfig({
+  html: {
+    title: 'example',
+  },
+});
+```
+
+For details of building configs, please refer to [「Modern.js Builder - Builder Config」](https://modernjs.dev/builder/en/guide/basic/builder-config.html).
+
+## Building Features
+
+Modern.js Builder provides a wealth of building features, including dozens of features such as JavaScript compilation, CSS compilation, static resource processing, hot module replacement, code compression, and TS type checking.
+
+We recommend you to read [「Modern.js Builder - All Features」](https://modernjs.dev/builder/en/guide/features.html) to learn all the building features provided by Modern.js Builder.

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