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

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 /Users/bytedance/github/modern.js/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

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

@@ -2,10 +2,10 @@
 sidebar_position: 1
 ---
 
-# dev
+# dev / start
 
 ```bash
-Usage: modern dev [options]
+Usage: modern dev / modern start [options]
 
 Development commands
 
@@ -19,8 +19,13 @@ Options:
 
 `modern dev` start a development server，watch file change，default support React Fast Refresh:
 
+`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
+
 ```bash
-App running at:
+$ modern dev
+
+info    Starting dev server...
+info    App running at:
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

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

@@ -5,35 +5,56 @@ sidebar_position: 7
 ```
 Usage: modern inspect [options]
 
-inspect internal webpack config
-
 Options:
   --env <env>           view the configuration in the target environment (default: "development")
   --output <output>     Specify the path to output in the dist (default: "/")
-  --no-console          Do not output the full result in shell
   --verbose             Show the full function in the result
   -c --config <config>  configuration file path, which can be a relative path or an absolute path
   -h, --help            show command help
 ```
 
-`modern inspect` command used to view the full webpack configuration of the project.
+`modern inspect` command used to view the [Modern.js Builder config](https://modernjs.dev/builder/en/guide/basic/builder-config.html) and webpack config of the project.
+
+After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
 
-Executing the command `npx modern inspect` in the project will output the webpack configuration on the shell, and will also generate a `webpack.client.inspect.js` file in the project's `dist` directory, which developers can open and view manually.
+- `builder.config.js`: The Modern.js Builder config to use at build time.
+- `webpack.config.web.js`: The webpack config used by to use at build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+```
 
 ## Configuration Env
 
-By default, the webpack configuration of the development environment is output. And the `env` option can be used to output the configuration of the production environment:
+By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
 
 ```bash
 modern inspect --env production
 ```
 
-## Configuration Type
+## Verbose content
+
+By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
+
+```bash
+modern inspect --verbose
+```
 
 ### 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.
+If the project has enabled SSR, an additional `webpack.config.node.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
 
-### Modern Configuration
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
 
-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.
+  - Builder Config: /root/my-project/dist/builder.config.js
+  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
+  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
+```

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

@@ -0,0 +1,32 @@
+---
+sidebar_position: 6
+---
+
+```bash
+Usage: modern serve [options]
+
+run server
+
+Options:
+  -c --config <config>  configuration file path, which can be a relative path or an absolute path
+  -h, --help            show command help
+  --api-only            only run API service
+```
+
+Usually use the `modern serve` command to enable project run in the production environment, and you need to execute the [`build'](/docs/apis/app/commands/build) command in advance to build the product.
+
+By default, the project will run in `localhost:8080`, you can modify the Server port number with `server.port`:
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  }
+})
+```
+
+import CommandTip from '@site-docs-en/components/command-tip.md'
+
+<CommandTip />
+
+

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/server.md

@@ -0,0 +1,31 @@
+---
+title: "*.[server|node].[tj]sx"
+sidebar_position: 8
+---
+
+Used in application projects to place server side code, it generally has the following two functions：
+
+1. When `*.tsx` and `*. [server|node].tsx` coexist, rendering on the server side will give preference to the `*. [server|node].tsx` file instead of the `*.tsx` file.
+
+2. When using [data loader](/docs/guides/basic-features/data-fetch), the server-side dependencies need to be re-exported from this file
+
+```tsx
+// routes/user/avatar.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { readFile } from './utils.server';
+
+type ProfileData = { /* some type declarations */ }
+
+export const loader = async(): ProfileData => {
+  const profile = await readFile('profile.json');
+  return profile;
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/user/utils.server.ts
+export * from 'fs-extra';
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/bootstrap.md

@@ -2,7 +2,7 @@
 title: bootstrap
 ---
 
-Used to start and mount App, usually without manual calls。This API is only required when using [Custom App](/docs/guides/advanced-features/custom-app).
+Used to start and mount App, usually without manual calls。This API is only required when using [Custom App](/docs/guides/concept/entries#自定义-app).
 
 ## Usage
 
@@ -41,7 +41,6 @@ type BootStrap<T = unknown> = (
 ```tsx
 import ReactDOM from 'react-dom/client'
 import { createApp, bootstrap } from '@modern-js/runtime';
-import { router, state } from '@modern-js/runtime/plugins';
 
 function App() {
   return <div>Hello Modern.js</div>;
@@ -49,7 +48,9 @@ function App() {
 
 const WrappedApp = createApp({
   // customized plugin
-  plugins: [router({}), state({})],
+  plugins: [
+    customPlugin(),
+  ],
 })(App);
 
 bootstrap(WrappedApp, 'root', undefined, ReactDOM);

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/create-app.md

@@ -2,7 +2,7 @@
 title: createApp
 ---
 
-Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/docs/guides/advanced-features/custom-app).
+Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/docs/guides/concept/entries#自定义-app).
 
 ## Usage
 
@@ -40,8 +40,7 @@ function App() {
 
 export default createApp({
   plugins: [
-    router({}),
-    state({}),
+    customPlugin()
   ]
 })(App);
 ```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/use-module-apps.md

@@ -7,7 +7,7 @@ Returns the React components of all micro-front-end sub-applications for freely
 ## Usage
 
 ```tsx
-import { useModuleApps } from '@modern/plugin-garfish';
+import { useModuleApps } from '@modern-js/runtime/garfish';
 ```
 
 :::info Turn on

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 serve        # 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/builder-plugins.md

@@ -0,0 +1,70 @@
+---
+title: builderPlugins
+sidebar_position: 10
+---
+
+- Type: `BuilderPlugin[]`
+- Default: `[]`
+
+Used to configure the Modern.js Builder plugin.
+
+Modern.js Builder is the build engine of Modern.js, please read [Builder](/docs/guides/basic-features/builder) for background. If you want to know how to write Builder plugins, you can refer to [Modern.js Builder - Introduce to Plugin](https://modernjs.dev/builder/en/plugins/introduction.html).
+
+## Precautions
+
+This option **is used to configure the Modern.js Builder plugins**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [plugins](docs/configure/app/builder-plugins) to configure Modern.js framework plugins.
+- Use [tools.webpack](/docs/configure/app/tools/webpack) or [tools.webpackChain](/docs/configure/app/tools/webpack-chain) to configure webpack plugins.
+- Use [tools.babel](/docs/configure/app/tools/babel) to configure babel plugins.
+
+## When to use
+
+In most scenarios, we recommend you to use the Modern.js framework plugin, which can be registered through the [plugins](docs/configure/app/plugins) config. Because the API provided by the framework plugin is richer and more capable, while the API provided by the Builder plugin can only be used to build scenes.
+
+When you need to reference some existing Builder plugins (and there is no related capability in Modern.js), or reuse Builder plugins between different frameworks, you can use the `builderPlugins` field to register them.
+
+## Example
+
+Below is an example of using the Builder plugin.
+
+### Using plugins on npm
+
+To use a plugin on npm, you need to install the plugin through the package manager and import it.
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [MyBuilderPlugin()],
+});
+```
+
+### Using local plugins
+
+Use the plugin in the local code repository, you can import it directly through the relative path import.
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from './plugin/myBuilderPlugin';
+
+export default defineConfig({
+  builderPlugins: [MyBuilderPlugin()],
+});
+```
+
+### Plugin configuration items
+
+If the plugin provides some custom configuration options, you can pass in the configuration through the parameters of the plugin function.
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    MyBuilderPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/en/docusaurus-plugin-content-docs/current/configure/app/dev/with-master-app.md

@@ -29,4 +29,3 @@ export default defineConfig({
 - moduleApp: `string` Online address of the main application.
 - moduleName: `Contact` The name of the child app (needs to match the module name registered in the main app)。
 
-For detailed usage, please refer to [Micro Front-end Sub-Application](/docs/guides/topic-detail/micro-frontend/debugging)。

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

@@ -3,18 +3,24 @@ title: plugins
 sidebar_position: 9
 ---
 
-* Type: `CliPlugin[]`
-* Default: `[]`
+- Type: `CliPlugin[]`
+- Default: `[]`
 
-Used to configure custom Modern.js plugins.
+Used to configure custom Modern.js framework plugins.
 
 For the way to write custom plugins, please refer to [How to Write Plugins](/docs/guides/topic-detail/framework-plugin/implement).
 
-This option is used to configure the framework plugin. If you need to configure the webpack plugin, please use [tools.webpack](/docs/configure/app/tools/webpack) or [tools.webpack Chain](/docs/configure/app/tools/webpack-chain); If you need to configure the babel plugin, please use [tools.babel](/docs/configure/app/tools/babel).
+## Precautions
+
+This config **is used to configure the Modern.js framework plugin**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [builderPlugins](docs/configure/app/builder-plugins) to configure Modern.js Builder plugins.
+- Use [tools.webpack](/docs/configure/app/tools/webpack) or [tools.webpackChain](/docs/configure/app/tools/webpack-chain) to configure webpack plugins.
+- Use [tools.babel](/docs/configure/app/tools/babel) to configure babel plugins.
 
 ## Plugin type
 
-There are three different plug-in mechanisms built into the Modern.js:
+There are three different type of framework plugins built into the Modern.js:
 
 - `CLI Plugin`，for local development, compilation and build phases, can extend various capabilities on the command line and compilation phases.
 - `Server Plugin`，for server-level.

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/source/disable-entry-dirs.md

@@ -0,0 +1,38 @@
+---
+title: source.disableEntryDirs
+
+sidebar_label: disableEntryDirs
+---
+
+* Type： `string[]`
+* Default： `[]`
+
+By default, application entries are identified based on the'src 'directory, you can disable some directories from being identified as application entries with this option.
+
+For example, when the configuration and directory structure is as follows：
+
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableEntryDirs: './src/one'
+  }
+})
+```
+
+``` title="Project directory structure"
+└── src/
+    ├── one/
+    |    └── App.tsx
+    ├── two/
+    |    └── routes/
+    └── env.d.ts
+```
+
+When this option is not set, Modern.js will generate two entries based on the project directory:
+- one
+- two
+
+When this option is set, `src/one` will not be recognized as an entry directory.
+
+A common usage is to configure the `src/common`, `src/components` directories to this option to avoid these directories being recognized as application entries.

package/en/docusaurus-plugin-content-docs/current/configure/app/source/entries.md

@@ -27,10 +27,34 @@ export default defineConfig({
 });
 ```
 
-Customized entry, only need to export `App` by default, Modern.js will generate a real entry file.
+By default, the configured entry is equivalent to `App.[jt]sx`, that is, the specified entry file only needs to export the root component of the application.
 
-When this behavior needs to be turned off, the value can be set to `Object` and the property `disableMount` can be set to `true`.
+For example the following directory structure:
 
+```bash
+.
+├── src
+│   └── entry
+│       ├── chat.tsx
+│       └── home.tsx
+└── package.json
+```
+
+With the content of the above default entry mechanism, Modern.js when analyzing the above directory, will not get any default entry.
+
+In cases where you do not want to change the directory structure (such as project migration), you can customize the entry through `source.entries`:
+
+
+```ts title="modern.config.js"
+export default defineConfig({
+  source: {
+    entries: {
+      home: './src/entry/home.tsx',
+      chat: './src/entry/chat.tsx',
+    },
+  },
+});
+```
 
 ## Object
 
@@ -60,3 +84,43 @@ export default defineConfig({
   },
 });
 ```
+
+By default, the configured entry is equivalent to `App.[jt]sx`. If you want the entry to be equivalent to the entry in build mode, you can set the value to'Object' and the property `disableMount` to `true`.
+
+## Combine Entry
+
+When `source.entries` is specified, the Modern.js merges the user-defined entry with the default entry obtained by analyzing the directory structure. The merging rule is:
+
+Compare the entry path set by the custom entry with the default entry path. When the entry paths are the same, the custom entry will override the default entry.
+
+For example the following directory structure:
+
+
+```bash
+.
+├── src
+│   ├── chat
+│   │   └── App.jsx
+│   └── home
+│       └── index.js
+└── package.json
+```
+
+Modern.js analyze the `src/` directory to get the default entries `chat` and `home`. When the user configures the following in the `modern.config.js` file:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      index: './src/home/index.js',
+    },
+  },
+};
+```
+
+You can see that the path of the custom entry `index` is the same as the path of the default entry `home`. During the merging process, `index` will override `home`, and the final entry is as follows:
+
+- `chat -> ./src/chat/App.jsx`
+- `index -> ./src/home/index.js`

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