@modern-js/main-doc 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @modern-js/main-doc
 
+## 2.11.0
+
+### Patch Changes
+
+- a8c08c3: feat: 添加 `source.transformImoprt`
+
+  feat: add `source.transformImoprt`
+
+- 304c950: fix: translate some chinese to english in en docs
+  fix: 将部分英文文档中的中文翻译为英文
+- Updated dependencies [a8c08c3]
+- Updated dependencies [b71cef1]
+  - @modern-js/builder-doc@2.11.0
+
+## 2.10.0
+
+### Patch Changes
+
+- 92d247f: fix: support tools.devServer.header include string[] type, remove get & delete & apply api in hook or middleware api
+  fix: 支持 tools.devServer.header 包含字符串数组类型，移除 Hook 和 Middleware 中对 响应 Cookie 的获取、删除操作
+- 19e552a: fix: main doc theme
+
+  fix: 首页深色模式问题
+
+- Updated dependencies [cfdbf80]
+  - @modern-js/builder-doc@2.10.0
+
 ## 2.9.0
 
 ### Patch Changes

package/docs/en/apis/app/hooks/src/server.mdx

@@ -4,31 +4,4 @@ sidebar_position: 8
 ---
 # *.[server|node].[tj]sx
 
-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](/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';
-```
+Used in application projects to place server side code, 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.

package/docs/en/apis/app/runtime/web-server/hook.mdx

@@ -38,9 +38,7 @@ type HookContext = {
     set: (key: string, value: string) => void;
     status: (code: number) => void;
     cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
+      set: (key: string, value: string, options?: any) => void;
       clear: () => void;
     };
     raw: (

package/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -46,11 +46,8 @@ type MiddlewareContext = {
     set: (key: string, value: string) => void;
     status: (code: number) => void;
     cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
+      set: (key: string, value: string, options?: any) => void;
       clear: () => void;
-      apply: () => void;
     };
     raw: (
       body: string,

package/docs/en/blog/index.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+---
+
+# Blog
+
+You can find the latest news about Modern.js here.
+

package/docs/en/configure/app/output/splitRouteChunks.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_label: splitRouteChunks
+---
+
+# output.splitRouteChunks
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+When using convention-based routing, the framework will split js and css based on the route to load on demand. If your project does not want to split js and css based on routes, you can set this option to `false`.
+
+Example:
+
+```ts
+export default {
+  output: {
+    splitRouteChunks: false,
+  },
+}
+```

package/docs/en/configure/app/source/config-dir.mdx

@@ -1,8 +1,8 @@
 ---
-title: source.configDir
 sidebar_label: configDir
 ---
-# configDir
+
+# source.configDir
 
 - **Type:** `string`
 - **Default:** `./config`

package/docs/en/configure/app/source/design-system.mdx

@@ -1,8 +1,8 @@
 ---
-title: source.designSystem
 sidebar_label: designSystem
 ---
-# designSystem
+
+# source.designSystem
 
 - **Type:** `Object`
 - **Default:** See configuration details below.

package/docs/en/configure/app/source/disable-default-entries.mdx

@@ -1,26 +1,19 @@
 ---
-title: source.disableDefaultEntries
 sidebar_label: disableDefaultEntries
 ---
-# disableDefaultEntries
+
+# source.disableDefaultEntries
 
 - **Type:** `boolean`
 - **Default:** `false`
 
-Turn off the function of automatically identifying the application build entry according to the project directory structure. By default, the Modern.js will get the corresponding build entry according to the project directory structure.
+Used to disable the function of automatically identifying the page entry according to the project directory structure.
 
 :::info
-By default, Modern.js will get the corresponding entry information according to the project directory structure. For details, please refer to [Entry](/guides/concept/entries).
-After configuring the shutdown mechanism, you need to configure the custom entry with [`source.entries`](/configure/app/source/entries).
-
-:::
-
-:::warning Warning
-Organizing your code according to the catalog specification provided by the Modern.js is recommended to make better use of the framework's capabilities and avoid some redundant configuration.
-
+By default, Modern.js will get the page entries according to the project directory structure. For details, please refer to [Entry](/guides/concept/entries).
 :::
 
-Set the following to turn off the default behavior:
+Set the following to disable the default behavior:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -29,3 +22,10 @@ export default defineConfig({
   },
 });
 ```
+
+After turning off the default behavior, you need to use [`source.entries`](/configure/app/source/entries) to configure custom entries.
+
+:::warning
+We recommend using the directory convention provided by Modern.js to organize the code, so as to better use the functions of the framework and avoid some redundant configurations.
+
+:::

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

@@ -1,14 +1,13 @@
 ---
-title: source.disableEntryDirs
-
 sidebar_label: disableEntryDirs
 ---
-# disableEntryDirs
+
+# source.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.
+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:
 

package/docs/en/configure/app/source/enable-async-entry.mdx

@@ -1,8 +1,8 @@
 ---
-title: source.enableAsyncEntry
 sidebar_label: enableAsyncEntry
 ---
-# enableAsyncEntry
+
+# source.enableAsyncEntry
 
 - **Type:** `boolean`
 - **Default:** `false`

package/docs/en/configure/app/source/entries-dir.mdx

@@ -1,13 +1,13 @@
 ---
-title: source.entriesDir
 sidebar_label: entriesDir
 ---
-# entriesDir
+
+# source.entriesDir
 
 - **Type:** `string`
 - **Default:** `./src`
 
-By default, the application entry will be identified according to the `src` directory. You can customize the identification directory of the application entry through this option.
+Modern.js will scan the `src` directory by default to identify the page entries, you can customize the identification directory of the page entries through this option.
 
 For example, when the configuration and directory structure are as follows:
 
@@ -24,16 +24,16 @@ export default defineConfig({
 └── src
     └── pages
         ├── a
-        │   └── App.jsx
+        │   └── App.tsx
         └── b
-            └── App.jsx
+            └── App.tsx
 ```
 
-Modern.js will generate the build entry `a` and entry `b` according to the `./src/pages` directory structure, the result is as follows:
+Modern.js will generate the build entry `a` and `b` according to the `./src/pages` directory structure, the result is as follows:
 
 ```js
- {
-   a: './src/pages/a/App.jsx',
-   b: './src/pages/b/App.jsx'
- }
+const entry = {
+  a: './src/pages/a/App.tsx',
+  b: './src/pages/b/App.tsx',
+};
 ```

package/docs/en/configure/app/source/entries.mdx

@@ -1,19 +1,36 @@
 ---
-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.
+# source.entries
 
-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).
+- **Type:**
 
-If you need to customize the build entry, you can specify it with this option.
+```ts
+type Entries = Record<
+  string,
+  | string
+  | {
+      entry: string;
+      disableMount?: boolean;
+    }
+>;
+```
+
+- **Default:** An entry object calculated from the directory structure of the current project.
+
+Used to configure custom page entries.
+
+:::tip When to use
+For most scenarios, the entries automatically generated by Modern.js according to the directory structure can already meet the requirements. For details, please refer to [entries](/guides/concept/entries).
+
+If you need to customize the page entry, you can set it through this option.
+
+:::
 
 ## String
 
-When the value is of type `string`, the file path of the entry:
+When the value of `entries` object is `string` type, it means the file path of the entry module:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -22,13 +39,14 @@ export default defineConfig({
   source: {
     entries: {
       // Specify a new entry named entry_customize
-      entry_customize: './src/home/test/index.js',
+      entry_customize: './src/home/test/index.ts',
     },
+    disableDefaultEntries: true,
   },
 });
 ```
 
-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.
+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:
 
@@ -41,17 +59,18 @@ For example the following directory structure:
 └── package.json
 ```
 
-With the content of the above default entry mechanism, Modern.js when analyzing the above directory, will not get any default entry.
+The above directory does not conform to the directory structure convention of Modern.js, therefore, Modern.js will not get any default entry when analyzing the directory structure.
 
 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"
+```ts title="modern.config.ts"
 export default defineConfig({
   source: {
     entries: {
       home: './src/entry/home.tsx',
       chat: './src/entry/chat.tsx',
     },
+    disableDefaultEntries: true,
   },
 });
 ```
@@ -60,8 +79,8 @@ export default defineConfig({
 
 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.
+- `entry`: `string`, entry file path.
+- `disableMount`: `boolean = false`, turn off the entry-scanning behavior of Modern.js.
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -71,25 +90,63 @@ export default defineConfig({
     entries: {
       entry_customize: {
         // entry file path
-        entry: './src/home/test/App.jsx',
+        entry: './src/home/test/App.tsx',
+      },
+    },
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Disable entry file generation
+
+By default, the configured entry is equivalent to `App.[jt]sx`, and Modern.js will automatically generate an entry file to reference your configured entry.
+
+If you want to disable the logic of Modern.js automatically generating the entry file, you can set the `disableMount` property to `true`.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    entries: {
+      entry_customize: {
+        entry: './src/home/test/index.tsx',
+        disableMount: true,
       },
-      // Use Conventional Routing
+    },
+    // Disable default ingress scanning
+    disableDefaultEntries: true,
+  },
+});
+```
+
+### Conventional Routing
+
+If you need to enable conventional routing for a custom entry, you can set `entry` to a directory path:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    entries: {
+      // enable conventional routing
       entry_spa: {
-        // The entry path of a conventional route must be set to a directory
+        // The entry path of conventional routing must be set to a directory
         entry: './src/about',
       },
     },
+    disableDefaultEntries: true,
   },
 });
 ```
 
-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`.
+## Entry Merge Rules
 
-## Combine Entry
+After setting `source.entries`, if `disableDefaultEntries: true` is not set, Modern.js will merge the custom entry with the entry obtained by analyzing the directory structure.
 
-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:
+The merge 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.
+- Compare the entry path set by the custom entry with the default entry path. When the entry path is consistent, the custom entry will override the default entry.
 
 For example the following directory structure:
 
@@ -97,13 +154,13 @@ For example the following directory structure:
 .
 ├── src
 │   ├── chat
-│   │   └── App.jsx
+│   │   └── App.tsx
 │   └── home
-│       └── index.js
+│       └── index.ts
 └── 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:
+Modern.js will analyze the `src/` directory to get the default entries `chat` and `home`. When the user configures the following in the `modern.config.ts` file:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -111,7 +168,7 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   source: {
     entries: {
-      index: './src/home/index.js',
+      index: './src/home/index.ts',
     },
   },
 };
@@ -119,5 +176,5 @@ export default defineConfig({
 
 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`
+- `chat -> ./src/chat/App.tsx`
+- `index -> ./src/home/index.ts`

package/docs/en/configure/app/source/plugin-import.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: pluginImport
+---
+
+# source.transformImport
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [source.transformImport](https://modernjs.dev/builder/en/api/config-source.html#sourcepluginimport).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/source/transformImport.md';
+
+<Main />

package/docs/en/configure/app/source/transform-import.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: transformImport
+---
+
+# source.transformImport
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [source.transformImport](https://modernjs.dev/builder/en/api/config-source.html#sourcetransformimport).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/source/transformImport.md';
+
+<Main />

package/docs/en/configure/app/tools/esbuild.mdx

@@ -1,20 +1,25 @@
 ---
-title: tools.esbuild
 sidebar_label: esbuild
 ---
-# esbuild
+
+# tools.esbuild
 
 - **Type:** `Object`
 - **Default:** `undefined`
 
 ## Introduction
 
-:::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.
 
+Modern.js provides esbuild plugin that allow you to use esbuild instead of babel-loader, ts-loader and terser for transformation and minification process.
+
+:::tip Recommend using SWC
+We recommend using SWC to transform and minify code rather than esbuild, because SWC supports more syntaxes, provides better code compression, and the compiled code has better compatibility.
+
+Therefore, we recommend that you use SWC instead of esbuild, please refer to [tools.swc](/configure/app/tools/swc) for usage.
+
 :::
 
-Modern.js provides esbuild plugin that allow you to use esbuild instead of babel-loader, ts-loader and terser for transformation and minification process.
 
 ## Configuration
 

package/docs/en/configure/app/tools/jest.mdx

@@ -1,9 +1,8 @@
 ---
-title: tools.jest
-
 sidebar_label: jest
 ---
-# jest
+
+# tools.jest
 
 - **Type:** `Object | Function`
 - **Default:** `{}`

package/docs/en/configure/app/tools/swc.mdx

@@ -1,8 +1,8 @@
 ---
-title: tools.swc
 sidebar_label: swc
 ---
-# swc
+
+# tools.swc
 
 - **Type:** `Object`
 - **Default:** `undefined`
@@ -13,6 +13,10 @@ sidebar_label: swc
 
 Modern.js Builder has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.
 
+:::tip
+When using Rspack as the bundler, SWC will be used for transpiling and compression by default, so you don't need to install or configure the SWC plugin.
+:::
+
 ## Install
 
 The `@modern-js/plugin-swc` plugin needs to be installed before use.

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

@@ -75,4 +75,5 @@ Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
 :::caution
 This feature only works when using Modern.js built-in Web Server.
 
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through html.template / tools.html will cause this feature not work.
 :::

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

@@ -4,7 +4,7 @@ sidebar_position: 1
 
 # Using Rspack
 
-import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack.md';
+import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack-tip.mdx';
 
 <Rspack />
 

package/docs/en/guides/advanced-features/ssr.mdx

@@ -22,8 +22,8 @@ export default defineConfig({
 
 Modern.js provides Data Loader, which is convenient for developers to fetch data under SSR and CSR. Each routing module, such as `layout.tsx` and `page.tsx`, can define its own Data Loader:
 
-```ts title="src/routes/page.tsx"
-export const loader = () => {
+```ts title="src/routes/page.loader.ts"
+export default () => {
   return {
     message: 'Hello World',
   };
@@ -49,6 +49,7 @@ However, developers still need to pay attention to the fallback of data, such as
 1. When you request the page on client-side page transitions, Modern.js sends an API request to the server, which runs Data Loader function.
 
 2. When using Data Loader, data fetching happens before rendering, Modern.js still supports fetching data when the component is rendered. See [Data Fetch](/guides/basic-features/data-fetch).
+
 :::
 
 ## Keep Rendering Consistent
@@ -225,7 +226,7 @@ The Node API is introduced in the component file, usually because of the use of
 
 ```ts
 import fse from 'fs-extra';
-export const loader = () => {
+export default () => {
   const file = fse.readFileSync('./myfile');
   return {
     ...

package/docs/en/guides/advanced-features/web-server.mdx

@@ -80,7 +80,7 @@ Modern.js provides a set of APIs by default for projects to use:
 ```ts
 import { Middlewre } from '@modern-js/runtime/server';
 
-export const middleware = (context, next) => {
+export const middleware: Middlewre = (context, next) => {
   const { source: { req, res } } = context;
   console.log(req.url);
   next();