@modern-js/main-doc 2.8.0 → 2.9.0

package/en/configure/app/source/disable-entry-dirs.mdx

@@ -1,39 +0,0 @@
----
-title: source.disableEntryDirs
-
-sidebar_label: disableEntryDirs
----
-# 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：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  source: {
-    disableEntryDirs: './src/one',
-  },
-});
-```
-
-```bash 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/configure/app/source/entries.mdx

@@ -1,123 +0,0 @@
----
-title: source.entries
-sidebar_label: entries
----
-# entries
-
-- **Type:** `Object = { [ entryName: string ]: string | Object }`
-- **Default:** Default entry object dynamically settled according to the current project directory structure.
-
-For most scenarios, Modern.js automatically generated entries according to the directory structure can meet most business requirements. For details, please refer to [Entries](/guides/concept/entries).
-
-If you need to customize the build entry, you can specify it with this option.
-
-## String
-
-When the value is of type `string`, the file path of the entry:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  source: {
-    entries: {
-      // Specify a new entry named entry_customize
-      entry_customize: './src/home/test/index.js',
-    },
-  },
-});
-```
-
-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.
-
-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
-
-When the value is `Object`, the following properties can be configured:
-
-- `entry`：`string`，entry file path.
-- `disableMount`：`boolean = false`，turn off Modern.js generate entry code.
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  source: {
-    entries: {
-      entry_customize: {
-        // entry file path
-        entry: './src/home/test/App.jsx',
-      },
-      // Use Conventional Routing
-      entry_spa: {
-        // The entry path of a conventional route must be set to a directory
-        entry: './src/about',
-      },
-    },
-  },
-});
-```
-
-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/guides/advanced-features/code-split.mdx

@@ -1,80 +0,0 @@
----
-title: Code Split
-sidebar_position: 6
----
-# Code Split
-
-Code Split is a common way to optimizing front-end resource loading. This doc will introduce three methods supported by Modern.js:
-
-:::info
-When you use Modern.js [Conventional routing](/guides/basic-features/routes#conventional-routing), by default it will do code splitting based on routing components, wrapping `Suspense` components, no need to do code splitting by yourself.
-
-:::
-
-- `import`
-- `React.lazy`
-- `loadable`
-
-## import
-
-use dynamic `import()`，`import` The JS modules pass to this API will be packaged into a separate JS file as a new packaging entry, for example:
-
-```ts
-import('./math').then(math => {
-  console.log(math.add(16, 26));
-});
-```
-
-The JS modules corresponding to the './math' path will be packaged in a separate JS file.
-
-## React.lazy
-
-The officially way provides by React to split component code.
-
-:::caution
-SSR is not supported in React 17 and below, and it is recommended that SSR applications for React 17 use loadable.
-
-:::
-
-```ts
-import React, { Suspense } from 'react';
-
-const OtherComponent = React.lazy(() => import('./OtherComponent'));
-const AnotherComponent = React.lazy(() => import('./AnotherComponent'));
-
-function MyComponent() {
-  return (
-    <div>
-      <Suspense fallback={<div>Loading...</div>}>
-        <section>
-          <OtherComponent />
-          <AnotherComponent />
-        </section>
-      </Suspense>
-    </div>
-  );
-}
-```
-
-For detail, see [React lazy](https://reactjs.org/docs/code-splitting.html#reactlazy).
-
-## loadable
-
-use `loadable` API，for example：
-
-```ts
-import loadable from '@modern-js/runtime/loadable';
-
-const OtherComponent = loadable(() => import('./OtherComponent'));
-
-function MyComponent() {
-  return <OtherComponent />;
-}
-```
-
-For detail, see [loadable API](/apis/app/runtime/utility/loadable).
-
-:::info
-SSR is supported out of the box by `loadable`.
-
-:::

package/en/guides/advanced-features/compatibility.mdx

@@ -1,78 +0,0 @@
----
-title: Compatibility
-sidebar_position: 5
----
-# Compatibility
-
-## Browserslist
-
-Modern.js supports the `browserslist` field in the `package.json` file, or a `.browserslistrc` file to specify the target browser range covered by the project.
-
-This value is used by ['@babel/preset-env'] (https://babeljs.io/docs/en/babel-preset-env) and ['autoprefixer'] (https://github.com/postcss/autoprefixer) to determine the JavaScript syntax features to be converted and the CSS browser prefix to be added.
-
-The default value in Modern.js as follow:
-
-```js
-['> 0.01%', 'not dead', 'not op_mini all'];
-```
-
-You can learn how to customize the browserslist [here](https://github.com/browserslist/browserslist).
-
-See Modern.js Builder docs to learn more [Browserslist](https://modernjs.dev/builder/en/guide/advanced/browserslist.html) info.
-
-:::note
-Modern.js also supports configuring [output.override Browserslist](/configure/app/output/override-browserslist) to override the default browserslist value.
-
-:::
-
-## Polyfill
-
-### Polyfill At Compile
-
-Modern.js inject the Polyfill code via [core-js] (https://github.com/zloirock/core-js) at compile time by default.
-
-By default, the required Polyfill code will be introduced according to the settings of the Browserslist, so there is no need to worry about the Polyfill problem of the project source code and third-party dependencies, but because it contains some Polyfill code that is not used, the final bundle size may be increased.
-
-:::info
-For case where Polyfill is not required for third-party dependencies, you can set ['output.polyfill'](/configure/app/output/polyfill) to `usage`, so that Babel compiles only Polyfill code based on the syntax used in the code.
-
-:::
-
-### Polyfill At Runtime
-
-Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
-
-- It will not be inserted into the code, reducing the code .
-- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster.
-
-exec `pnpm run new` to enable this features：
-
-```bash
-? Action Enable features
-? Enable features Enable UA-based Polyfill Feature
-```
-
-After executing the command, register the Polyfill plugin in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import polyfillPlugin from '@modern-js/plugin-polyfill';
-
-export default defineConfig({
-  plugins: [..., polyfillPlugin()],
-});
-```
-
-After configuring `output.polyfill` as `ua` and executing `pnpm run build & & pnpm run serve` to start the server, visiting the page can see that the HTML product contains the following script:
-
-```js
-<script src="/__polyfill__" crossorigin></script>
-```
-
-Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
-
-![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
-
-:::caution
-This feature only works when using Modern.js built-in Web Server.
-
-:::

package/en/guides/advanced-features/eslint.mdx

@@ -1,148 +0,0 @@
----
-title: ESLint
-sidebar_position: 8
----
-# ESLint
-
-**Modern.js ESLint Rules** Is the full set of **ESLint** rules，includes `@modern-js` （Lint rules for Node.js projects）and `@modern-js-app`（Lint rules for web projects）。
-
-More ESLint usage is described below with specific questions.
-
-## Q: How To Deal With Lint
-
-### Automatic Fix
-
-Most problems will be solved by the automatic fix of ESLint rules or the code formatting of [Prettier](https://prettier.io/) (which has been integrated into ESLint), and the developer does not need to care about the details of the problem and how to solve it.
-
-:::info
-This kind of automatic fix is mainly performed when the IDE saves the file, and a few will be automatically fix on submit.
-:::
-
-### Batch Automatic Fix
-
-In rare cases, such as when an old project is migrated, the following commands can be executed to repair and inspect all files in bulk:
-
-```bash
-pnpm run lint:error
-```
-
-### Manual Fix
-
-For problems that cannot be automatically fixed, you can click the rule link in the problem prompt box in the IDE to open the document of this rule to view the explanation and solution of the problem.
-
-### Claim Exceptions
-
-At this stage, some rules are not smart enough, and in most cases there will be great benefits, and in a few cases it may not apply. But if the entire rule is turned off or changed for these few cases, the gain is not worth the loss.
-
-In this case, you can use the [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) comment to mark the code blocks that meet the **rare case**, stating that this is an exception and should be ignored. For example:
-
-```js
-/* eslint-disable filenames/match-exported */
-...
-/* eslint-enable filenames/match-exported */
-```
-
-:::info
-Enter eslint in the VS Code editor, a prompt box about `eslint-disable` will automatically appear, select the prompt option to generate the corresponding comment pair.
-:::
-
-[Modern.js ESLint Rule Set] requires that [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) must be used in pairs, the scope to be affected must be clearly expressed, and what rules to disable within this scope must be clearly expressed, the purpose is to make **exceptions** Clear, minimized scope to avoid abuse of [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules), resulting in code that does not belong to the exception being disabled by the rule.
-
-## Q: How to customize ESLint rules
-
-### The `eslintConfig` field in `package.json` in the root directory
-
-This place is the default ESLint configuration for the entire repository and is designed for pure Node.js code (which can only run in Node.js).
-
-If the project does have special requirements or inevitable compatibility issues with some rules (not exceptions), you can add rule configuration here. This configuration will take precedence over the default [Modern.js ESLint ruleset], such as:
-
-
-```json
- "eslintConfig": {
-    "extends": [
-      "@modern-js"
-    ],
-    "rules": {
-      "filenames/match-exported": "off"
-    }
-  },
-
-```
-
-### `src/.eslintrc.js`
-
-The application project and module project of Modern.js will have this configuration file by default in the source code directory, which is designed for Universal JS code.
-
-:::info
-Universal JS code is code that can run on both the browser side and the server side.
-:::
-
-If the project does have special requirements or inevitable compatibility issues with some rules (not exceptions), you can add a rule configuration here, which will take precedence over the default [Modern.js ESLint ruleset], such as:
-
-```js
-// eslint-disable-next-line import/no-commonjs
-module.exports = {
-  root: true,
-  extends: ['@modern-js-app'],
-  parserOptions: {
-    tsconfigRootDir: __dirname,
-    project: ['../tsconfig.json'],
-  },
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-
-If necessary, you can continue to add the `.eslintrc.js` file in different subdirectories, and make special configuration for the code in this subdirectory:
-
-```js
-module.exports = {
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-
-:::tip
-Note: It is not necessary to use the `extends` field, it will automatically inherit the configuration of the parent directory.
-
-:::
-
-### `eslintIgnore` field in `package.json`
-
-Adding directories that contain `.js`, `.jsx`, `.ts`, `.tsx` files, but do not require code inspection and automatic repair, to `eslintIgnore` can optimize the speed of ESLint inspection, such as:
-
-```json
- "eslintIgnore": [
-    "node_modules",
-    "dist",
-    "output"
-  ],
-```
-
-## Q: How to upgrade the version of the ESLint plugin
-
-As long as it is not a change in the Major version (the "^" symbol that does not comply with the [Semver](https://semver.org/) rule), you can specify this dependency directly in the `package.json` of the business project, delete the Lock file (or try to manually delete the Lock file). the contents of this package name in the file), execute `pnpm install` to reinstall the dependency and generate a new Lock file.
-
-After doing this, the plugin should only exist in the `./node_modules` directory of the business project and be upgraded to the version you specified.
-
-:::tip
-- Major version is the major version number. For more information, please read [[Semantic Versioning](https://semver.org/#summary) ].
-- All upstream projects encapsulated by Modern.js (such as ESLint, [ESLint plugin](https://eslint.org/docs/user-guide/configuring/plugins#plugins), [React Router](https://reactrouter.com/), etc.) can also be upgraded in this way.
-- Modern.js will also try to upgrade these upstream dependencies as timely as possible in each release.
-- Major version upgrades need to be published by Modern.js.
-
-:::
-
-## Q: WebStorm sometimes reports ESLint errors
-
-Since WebStorm believes that the ESLint execution directory is determined based on the `.eslintrc'` file. Therefore, the placement of the `src/.eslintrc` file location will cause the location specified by the `tsconfig.json` file (in the project root directory) to not be found in the'src/'directory.
-
-you need to configure it manually:
-
-```json
---parser-options=project:../tsconfig.json
-```
-
-![webstorm-lint-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/webstorm-lint-error.png)

package/en/guides/advanced-features/rspack-start.mdx

@@ -1,65 +0,0 @@
----
-title: Rspack Start
-sidebar_position: 1
----
-
-# Rspack Start
-
-[Rspack](https://www.rspack.dev/) is a Rust-based web bundler developed by the ByteDance Web Infra team. The core architecture of Rspack is aligned with the implementation of webpack, and provides out-of-the-box support for commonly used build features.
-
-Rspack optimizes compilation performance by:
-
-- Highly LTO optimized Native code.
-- Take full advantage of multi-core, and the entire compilation process is fully optimized for multi-threading.
-- On-demand compilation based on request (Lazy Compilation), reducing the number of modules per compilation to improve the speed of cold start.
-
-## Initializing an Rspack project
-
-The Modern.js generator provides an interactive question-and-answer interface to initialize a project. To create an Rspack project, simply select the **Rspack** build tool by running:
-
-import InitRspackApp from "@site-docs-en/components/init-rspack-app"
-
-<InitRspackApp />
-
-After the project is created, you can experience the project by running `pnpm run dev`. For more project information, please refer to [Quick Start](/guides/get-started/quick-start.html).
-
-:::tip
-When using Rspack as the bundler, the following features are currently not supported:
-
-- Server-side rendering (SSR)
-- Static Site Generation (SSG)
-- Micro Frontend.
-- Storybook debugging.
-
-:::
-
-## Migrating from webpack to Rspack
-
-You can enable Rspack build by running `pnpm run new`:
-
-```bash
-$ pnpm run new
-? Action： Enable features
-? Enable features： Enable Rspack Build
-```
-
-After executing the command, enable the Rspack build in `modern.config.ts`:
-
-```ts title=modern.config.ts
-import appTools, { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig<'rspack'>({
-  runtime: {
-    router: true,
-  },
-  plugins: [
-    appTools({
-      bundler: 'experimental-rspack',
-    }),
-  ],
-});
-```
-
-:::tip
-Migrating from webpack to Rspack may have some differences in build and configuration capabilities. For more details, please refer to [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).
-:::

package/en/guides/advanced-features/ssg.mdx

@@ -1,116 +0,0 @@
----
-title: Static Site Generation
-sidebar_position: 4
----
-# Static Site Generation
-
-Static Site Generation is a solution for rendering complete static web pages at build time based on data and templates.
-
-First need to execute `pnpm run new` to enable the SSG features:
-
-```bash
-? Action Enable features
-? Enable features Enable SSG
-```
-
-After execute script，register SSG plugin in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import ssgPlugin from '@modern-js/plugin-ssg';
-
-export default defineConfig({
-  output: {
-    ssg: true,
-  },
-  plugins: [..., ssgPlugin()],
-});
-```
-
-SSG in **Conventional Routing** and **Self-controlled Routing** has different usage.
-
-### Conventional Routing
-
-Modern.js generate routes based on the file structure under the entry, so the framework can collect complete routing information.
-
-For example, the following is a project directory structure using conventional routing:
-
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
-
-The above file directory will generate the following three routes:
-
-- `/`
-- `/user`
-- `/user/profile`
-
-:::note
-If you don't know the rules for routing, you can first check [routes](/guides/basic-features/routes).
-
-:::
-
-add component to `src/routes/page.tsx`：
-
-```jsx title="src/routes/page.tsx"
-export default () => {
-  return <div>Index Page</div>;
-};
-```
-
-SSG is also render in Node.js. So we can enable SSR in developmenet env, expose code problems in advance and verify SSG rendering effect：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  server: {
-    ssr: process.env.NODE_ENV === 'development',
-  }
-}
-```
-
-Execute the `pnpm run dev` command in the project to view the `dist/` directory, and only generate an HTML file `main/index.html`.
-
-Execute the `pnpm run build` command in the root path of the project. After the construction is completed, view the `dist/` directory, and generate `main/index.html`, `main/user/index.html` and `main/user/profile/index.html` three HTML files, the content corresponds to the above three routes.
-
-Using **Conventional Routing**, each route will generate a HTML file. Looking at the `main/index.html`, we can find the text content containing the `Index Page`, which is exactly the effect of SSG.
-
-After executing `pnpm run serve` to start the project, visit the page in the Network, view the document returned by the request. The document contains the complete page content rendered by the component.
-
-### Self-controlled Routing
-
-**Self-controlled routing** is a custom routing through component code, which requires the application to run to obtain accurate routing information. Therefore, the SSG function cannot be used out of the box. At this time, the user needs to inform the Modern.js framework in advance which routes need to enable the SSG.
-
-For example, there is the following code, which contains multiple routes. When setting `output.ssg` to `true`, only the entry route '/' will be rendered by default:
-
-import SelfRouteExample from "@site-docs/components/self-route-example";
-
-<SelfRouteExample />
-
-If we want to enable the SSG of `/about` at the same time, we can configure the `output.ssg` to tell Modern.js to enable the SSG of the specified route.
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  output: {
-    ssg: {
-      routes: ['/', '/about'],
-    },
-  },
-});
-```
-
-run `pnpm run build` and `pnpm run serve`，access `http://localhost:8080/about`. In the Preview view, you can see that the page has been rendered.
-
-Looking at the bundle file, a new `main/about/index.html` file has been added in the `dist/` directory.
-
-:::info
-The above only introduces the single entry, more related content can be viewed [SSG API](/configure/app/output/ssg).
-
-:::