@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/en/configure/app/tools/dev-server.mdx

@@ -15,118 +15,12 @@ Modern.js does not directly use [webpack-dev-server](https://webpack.js.org/api/
 
 ### Options
 
-#### after
-
-:::warning
-**Deprecated**: This configuration is deprecated, please use [dev.setupMiddlewares](https://modernjs.dev/en/configure/app/dev/setup-middlewares) instead.
-:::
-
-- **Type:** `Array`
-- **Default:** `[]`
-
-Provides the ability to execute custom middleware after all other middleware internally within the server.
-
-```js
-export default {
-  tools: {
-    devServer: {
-      after: [
-        async (req, res, next) => {
-          console.log('after dev middleware');
-          next();
-        },
-      ],
-    },
-  },
-};
-```
-
-`webpack-dev-server` uses Express as the server-side framework. Modern.js does not use any framework, and the `req` and `res` in the above middleware are all native Node objects. Therefore, the Express middleware used in `webpack-dev-server` may not be directly usable in Modern.js.
-
-If you want to migrate the Express middleware used in `webpack-dev-server`, you can use the following method to pass the Express app as middleware:
-
-```js
-import expressMiddleware from 'my-express-middleware';
-import express from 'express';
-
-// init Express app
-const app = express();
-app.use(expressMiddleware);
-
-export default {
-  tools: {
-    devServer: {
-      after: [app],
-    },
-  },
-};
-```
-
-#### before
-
-:::warning
-**Deprecated**: This configuration is deprecated, please use [dev.setupMiddlewares](https://modernjs.dev/en/configure/app/dev/setup-middlewares) instead.
-:::
-
-- **Type:** `Array`
-- **Default:** `[]`
-
-Provides the ability to execute custom middleware prior to all other middleware internally within the server.
-
-```js
-export default {
-  tools: {
-    devServer: {
-      before: [
-        async (req, res, next) => {
-          console.log('before dev middleware');
-          next();
-        },
-      ],
-    },
-  },
-};
-```
-
-#### client
+#### compress
 
 :::warning
-**Deprecated**: This configuration is deprecated, please use [dev.client](https://modernjs.dev/en/configure/app/dev/client) instead.
+**Deprecated**: This configuration is deprecated, please use [dev.server.compress](https://modernjs.dev/en/configure/app/dev/server) instead.
 :::
 
-- **Type:**
-
-```ts
-{
-    /** Specify a protocol to use */
-    protocol?: string;
-    /** The path which the middleware is serving the event stream on */
-    path?: string;
-    /** Specify a port number to listen for requests on */
-    port?: string;
-    /** Specify a host to use */
-    host?: string;
-}
-```
-
-- **Default:**
-
-```js
-const defaultConfig = {
-  path: '/webpack-hmr',
-  // By default it is set to the port number of the dev server
-  port: '',
-  // By default it is set to "location.hostname"
-  host: '',
-  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
-  protocol: '',
-};
-```
-
-The config of HMR client, which are usually used to set the WebSocket URL of HMR.
-
-#### compress
-
 - **Type:** `boolean`
 - **Default:** `true`
 
@@ -144,32 +38,12 @@ export default {
 };
 ```
 
-#### devMiddleware
+#### headers
 
 :::warning
-**Deprecated**: This configuration is deprecated, please use [dev.writeToDisk](https://modernjs.dev/en/configure/app/dev/write-to-disk) instead.
+**Deprecated**: This configuration is deprecated, please use [dev.server.headers](https://modernjs.dev/en/configure/app/dev/server) instead.
 :::
 
-- **Type:**
-
-```js
-{
-  writeToDisk: boolean | ((filename: string) => boolean);
-}
-```
-
-- **Default:**
-
-```js
-{
-  writeToDisk: (file: string) => !file.includes('.hot-update.'),
-}
-```
-
-The config of devMiddleware. Current options is the subset of [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware).
-
-#### headers
-
 - **Type:** `Record<string, string>`
 - **Default:** `undefined`
 
@@ -189,6 +63,10 @@ export default {
 
 #### historyApiFallback
 
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.server.historyApiFallback](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
 - **Type:** `boolean | ConnectHistoryApiFallbackOptions`
 - **Default:** `false`
 
@@ -206,128 +84,12 @@ export default {
 
 For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation.
 
-#### hot
-
-:::warning
-**Deprecated**: This configuration is deprecated, please use [dev.hmr](https://modernjs.dev/en/configure/app/dev/hmr) instead.
-:::
-
-- **Type:** `boolean`
-- **Default:** `true`
-
-Enable [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) feature.
-
-#### https
-
-:::warning
-**Deprecated**: This configuration is deprecated, please use [dev.https](https://modernjs.dev/en/configure/app/dev/https) instead.
-:::
-
-- **Type:** `boolean | { key: string; cert: string }`
-- **Default:** `false`
-
-By default, DevServer will be served over HTTP. It can optionally be served over HTTPS by setting `devServer.https` to `true`, and will disable the HTTP server.
-
-You can also manually pass in the certificate and corresponding private key required by the HTTPS server:
-
-```ts
-export default {
-  tools: {
-    devServer: {
-      https: {
-        key: fs.readFileSync('certificates/private.pem'),
-        cert: fs.readFileSync('certificates/public.pem'),
-      },
-    },
-  },
-};
-```
-
-#### liveReload
-
-:::warning
-**Deprecated**: This configuration is deprecated, please use [dev.liveReload](https://modernjs.dev/en/configure/app/dev/live-reload) instead.
-:::
-
-- **Type:** `boolean`
-- **Default:** `true`
-
-By default, the DevServer will reload/refresh the page when file changes are detected (`devServer.hot` option must be disabled in order for liveReload to take effect). Disable `devServer.liveReload` by setting it to `false`.
-
-#### setupMiddlewares
+#### proxy
 
 :::warning
-**Deprecated**: This configuration is deprecated, please use [dev.setupMiddlewares](https://modernjs.dev/en/configure/app/dev/setup-middlewares) instead.
+**Deprecated**: This configuration is deprecated, please use [dev.server.proxy](https://modernjs.dev/en/configure/app/dev/server) instead.
 :::
 
-- **Type:**
-
-```js
-Array<
-  (
-    middlewares: {
-      unshift: (...handlers: RequestHandler[]) => void;
-      push: (...handlers: RequestHandler[]) => void;
-    },
-    server: {
-      sockWrite: (
-        type: string,
-        data?: string | boolean | Record<string, any>,
-      ) => void;
-    },
-  ) => void
->;
-```
-
-- **Default:** `undefined`
-
-Provides the ability to execute a custom function and apply custom middlewares.
-
-The order among several different types of middleware is: `devServer.before` => `unshift` => internal middlewares => `push` => `devServer.after`.
-
-```js
-export default {
-  tools: {
-    devServer: {
-      setupMiddlewares: [
-        (middlewares, server) => {
-          middlewares.unshift((req, res, next) => {
-            next();
-          });
-
-          middlewares.push((req, res, next) => {
-            next();
-          });
-        },
-      ],
-    },
-  },
-};
-```
-
-It is possible to use some server api to meet special scenario requirements:
-
-- sockWrite. Allow send some message to hmr client, and then the hmr client will take different actions depending on the message type. If you send a "content changed" message, the page will reload.
-
-```js
-export default {
-  tools: {
-    devServer: {
-      setupMiddlewares: [
-        (middlewares, server) => {
-          // add custom watch & trigger page reload when change
-          watcher.on('change', changed => {
-            server.sockWrite('content-changed');
-          });
-        },
-      ],
-    },
-  },
-};
-```
-
-#### proxy
-
 - **Type:** `Record<string, string> | Record<string, ProxyDetail>`
 - **Default:** `undefined`
 
@@ -389,16 +151,16 @@ type ProxyOptions =
   | ProxyDetail;
 ```
 
-In addition to the http-proxy-middleware option, we also support the bypass and context configuration:
+In addition to the http-proxy-middleware options, two configuration items are also supported: bypass and context:
 
-- bypass: bypass the proxy based on the return value of a function.
-  - Return `null` or `undefined` to continue processing the request with proxy.
-  - Return `false` to produce a 404 error for the request.
-  - Return a path to serve from, instead of continuing to proxy the request.
-- context: If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a context property.
+- bypass: Bypass the proxy based on the return value of the function.
+  - Returning `null` or `undefined` will continue to process the request with proxy.
+  - Returning `false` will return a 404 error.
+  - Returning a specific service path will use this path to replace the original request path.
+- context: If you want to proxy multiple specific paths to the same target, you can use the context configuration item.
 
 ```js
-// custom bypass
+// Custom bypass method
 export default {
   tools: {
     devServer: {
@@ -419,7 +181,7 @@ export default {
 ```
 
 ```js
-// proxy multiple
+// Proxy multiple paths to the same target
 export default {
   tools: {
     devServer: {
@@ -436,6 +198,10 @@ export default {
 
 #### watch
 
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.server.watch](https://modernjs.dev/en/configure/app/dev/server) instead.
+:::
+
 - **Type:** `boolean`
 - **Default:** `true`
 

package/docs/en/configure/app/tools/html-plugin.mdx

@@ -17,7 +17,8 @@ const defaultOptions = {
   filename, // 基于 `output.distPath` 和 `entryName` 生成
   templateParameters, // 对应 `html.templateParameters` 配置
   chunks: [entryName],
-  minify: { // // generated based on `output.disableMinimize` and `output.minify`
+  minify: {
+    // generated based on `output.minify`
     removeComments: false,
     useShortDoctype: true,
     keepClosingSlash: true,
@@ -37,8 +38,7 @@ const defaultOptions = {
 SSR Application does not enable the `minify.removeComments` configuration, otherwise the SSR rendering will fail.
 :::
 
-
-The configs of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) or [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) can be modified through `tools.htmlPlugin`.
+The configs of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

package/docs/en/configure/app/tools/lightningcss-loader.mdx

@@ -6,7 +6,6 @@ title: lightningcssLoader
 
 - **Type:** `Rspack.LightningcssLoaderOptions | Function | boolean`
 - **Default:** `Rspack.LightningcssLoaderOptions | Function | boolean`
-- **Bundler:** `only support rspack`
 
 You can configure [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) through `tools.lightningcssLoader`.
 

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

@@ -24,7 +24,7 @@ You can set the options of [builtin:swc-loader](https://rspack.rs/guide/features
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
-export default defineConfig<'rspack'>({
+export default defineConfig({
   tools: {
     swc: {
       jsc: {
@@ -67,45 +67,3 @@ This means that you must to choose an SWC plugin that matches the current versio
 If you encounter the above issues, a common solution is to upgrade both the Modern.js and SWC plugins to the latest versions.
 
 For details, please refer to [Rsbuild - SWC Plugin Version](https://rsbuild.rs/guide/basic/configure-swc#swc-plugin-version).
-
-## Used in Webpack mode
-
-import EnableSWC from '@site-docs-en/components/enableSwc.mdx';
-
-<EnableSWC />
-
-### Config
-
-You can set the SWC compilation behavior through the `tools.swc` config.
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc: {
-      jsMinify: {
-        compress: {},
-        mangle: true,
-      },
-    },
-  },
-});
-```
-
-Or using function to have more customize config, or to modify the default config.
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc(config, { setConfig }) {
-      // Used for transpiling decorator of mobx correctly
-      setConfig(config, 'jsc.transform.useDefineForClassFields', true);
-    },
-  },
-});
-```
-
-For config details, please refer to [SWC Plugin Configuration](/plugin/official/cli-plugins/plugin-swc.html#config).

package/docs/en/configure/app/usage.mdx

@@ -43,15 +43,6 @@ export default defineConfig({
 });
 ```
 
-When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify the `<'rspack'>` generic for `defineConfig`:
-
-```diff title=modern.config.ts
-- export default defineConfig({
-+ export default defineConfig<'rspack'>({
-  // ...
-});
-```
-
 #### modern.config.js
 
 If you are developing a non-TypeScript project, you can use the `.js` format for the configuration file:
@@ -95,9 +86,9 @@ export default defineConfig(({ env, command }) => ({
 This function accepts the following parameters:
 
 - `env`: Corresponds to the value of `process.env.NODE_ENV`.
-  - When running `modern dev` or `modern start`, the value of `env` is `development`.
+  - When running `modern dev`, the value of `env` is `development`.
   - When running `modern build` or `modern serve`, the value of `env` is `production`.
-- `command`: Corresponds to the current command being run, such as `dev`, `start`, `build`, or `serve`.
+- `command`: Corresponds to the current command being run, such as `dev`, `build`, or `serve`.
 
 #### Exporting Asynchronous Functions
 
@@ -159,7 +150,6 @@ Due to the limitations of the JSON file format, only simple types such as number
 #### Notes
 
 - It is not recommended to use both `package.json` and `modern.config.js` for configuration simultaneously. If both are used and conflicts arise, Modern.js will prompt an error in the command line.
-- The `@modern-js/runtime` exports a similarly named [defineConfig](/apis/app/runtime/app/define-config) API, so please be careful to distinguish between them.
 
 ### Local Debugging Configuration
 
@@ -197,7 +187,7 @@ The configuration in the `modern.config.local.ts` file will be deeply merged wit
 
 When using `modern.config.local.ts`, please note the following:
 
-- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` or `modern start` commands and will not be loaded during `modern build`.
+- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` commands and will not be loaded during `modern build`.
 - The priority of the `modern.config.local.ts` file is higher than both `modern.config.ts` and the `modernConfig` field in `package.json`.
 - Since `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the code repository. Ensure that the project's `.gitignore` file includes `modern.config.local.ts` and similar files.
 
@@ -257,18 +247,6 @@ Modern.js exports the `AppUserConfig` type, which corresponds to the type of the
 import type { AppUserConfig } from '@modern-js/app-tools';
 
 const config: AppUserConfig = {
-  tools: {
-    webpack: {},
-  },
-};
-```
-
-When using Rspack as the bundler, due to some differences in configuration types between webpack and Rspack, you need to specify the `<'rspack'>` generic for `AppUserConfig`:
-
-```ts title="modern.config.ts"
-import type { AppUserConfig } from '@modern-js/app-tools';
-
-const config: AppUserConfig<'rspack'> = {
   tools: {
     rspack: {},
   },
@@ -284,11 +262,11 @@ If the current Runtime configuration needs to be used both at compile time and r
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
-import { statePlugin } from '@modern-js/plugin-state';
+import { xxPlugin } from '@modern-js/plugin-xx';
 
 export default defineConfig({
   plugins: [
-    statePlugin({
+    xxPlugin({
       /** Add parameters here */
     }),
   ],

package/docs/en/guides/_meta.json

@@ -29,5 +29,9 @@
     "name": "troubleshooting",
     "label": "troubleshooting"
   },
-  "deprecated"
+  {
+    "type": "dir",
+    "name": "upgrade",
+    "label": "Upgrade"
+  }
 ]

package/docs/en/guides/advanced-features/_meta.json

@@ -23,5 +23,11 @@
     "label": "server-monitor",
     "collapsed": true
   },
+  {
+    "type": "dir",
+    "name": "international",
+    "label": "Internationalization",
+    "collapsed": true
+  },
   "web-server"
 ]

package/docs/en/guides/advanced-features/bff/_meta.json

@@ -1 +1,9 @@
-["function", "frameworks", "extend-server", "sdk", "upload", "cross-project"]
+[
+  "function",
+  "frameworks",
+  "operators",
+  "extend-server",
+  "sdk",
+  "upload",
+  "cross-project"
+]

package/docs/en/guides/advanced-features/bff/cross-project.mdx

@@ -7,7 +7,7 @@ Cross-project invocation consists of **producer** and **consumer** sides. The pr
 
 ## BFF Producer
 
-Upgrade Modern.js dependencies to version x.64.4 or higher, then enable cross-project invocation via configuration. Projects with BFF capabilities enabled can act as BFF producers, or you can create standalone BFF applications.
+Enable cross-project invocation via configuration. Projects with BFF capabilities enabled can act as BFF producers, or you can create standalone BFF applications.
 When executing `dev` or `build`, the following artifacts for consumers will be automatically generated:
 - API functions under the `dist/client` directory
 - Runtime configuration functions under the `dist/runtime` directory
@@ -38,12 +38,6 @@ To provide type hints for the integrated invocation SDK, enable the `declaration
 }
 ```
 
-### Create BFF Application
-
-import CreateApi from "@site-docs-en/components/create-bff-api-app"
-
-<CreateApi/>
-
 ## BFF Consumer
 
 :::info
@@ -90,7 +84,7 @@ The `configure` function from `${package_name}/runtime` supports domain configur
 
 ```ts title="src/routes/page.tsx"
 import { configure } from '${package_name}/runtime';
-import { configure as innerConfigure } from '@modern-js/runtime/bff';
+import { configure as innerConfigure } from '@modern-js/plugin-bff/client';
 import axios from 'axios';
 
 configure({

package/docs/en/guides/advanced-features/bff/extend-server.mdx

@@ -6,17 +6,33 @@ Modern.js allows users to freely extend the BFF Server through [Middleware](/gui
 
 ## Using Middleware
 
+:::tip Version Consistency
+Before using middleware, you need to install the `@modern-js/server-runtime` dependency. Make sure the version of `@modern-js/server-runtime` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/server-runtime`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<version>
+```
+
+:::
+
 Developers can use middleware by configuring middlewares in `server/modern.server.ts`. The following describes how to write a BFF middleware manually to add permission verification:
 
 ```ts title="server/modern.server.ts"
 import {
   type MiddlewareHandler,
   defineServerConfig,
+  getCookie,
 } from '@modern-js/server-runtime';
 
 const requireAuthForApi: MiddlewareHandler = async (c, next) => {
   if (c.req.path.startsWith('/api') && c.req.path !== '/api/login') {
-    const sid = c.req.cookie('sid');
+    const sid = getCookie(c, 'sid');
     if (!sid) {
       return c.json({ code: -1, message: 'need login' }, 400);
     }
@@ -30,9 +46,8 @@ export default defineServerConfig({
       name: 'require-auth-for-api',
       handler: requireAuthForApi,
     },
-  ]
+  ],
 });
-
 ```
 
 Then add a regular BFF function `api/lambda/hello.ts`:

package/docs/en/guides/advanced-features/bff/frameworks.mdx

@@ -7,19 +7,6 @@ title: Runtime Framework
 
 Modern.js uses [Hono.js](https://hono.dev/) as the BFF and Server runtime framework, so you can [extend BFF Server](/guides/advanced-features/bff/extend-server.html) based on the Hono.js ecosystem.
 
-## Getting Request Context
+import Hono from '@site-docs-en/components/hono';
 
-Sometimes in BFF functions, it's necessary to obtain the request context to handle more logic. In such cases, you can use `useHonoContext` to get it:
-
-```ts title="api/lambda/hello.ts"
-import { useHonoContext } from '@modern-js/plugin-bff/hono'
-export const get = async () => {
-  const c = useHonoContext();
-  console.info(`access url: ${c.req.url}`);
-  return 'Hello Modern.js'
-};
-```
-
-:::info
-For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-hono-context).
-:::
+<Hono />

package/docs/en/guides/advanced-features/bff/function.mdx

@@ -6,9 +6,9 @@ This invocation method is called **unified invocation**, where developers do not
 
 ## Enable BFF
 
-import EnableBFF from "@site-docs-en/components/enable-bff"
+import EnableBFF from '@site-docs-en/components/enable-bff';
 
-<EnableBFF/>
+<EnableBFF />
 
 ## BFF Functions
 
@@ -34,10 +34,6 @@ export default () => {
 };
 ```
 
-:::tip
-After running the `new` command, the Modern.js generator will automatically configure the `@api` alias in `tsconfig.json`, allowing you to import functions directly using the alias.
-:::
-
 The function imported in `src/routes/page.tsx` will be automatically converted into an API call, eliminating the need to use an SDK or Web Fetch to call the API.
 
 After running `pnpm run dev`, open `http://localhost:8080/` and you can see that the page displays the content returned by the BFF function. In the Network tab, you can see a request was made to `http://localhost:8080/api/hello`.
@@ -191,7 +187,7 @@ Parameters following the dynamic path are an object called `RequestOption`, whic
 In a standard function without dynamic routes, `RequestOption` can be obtained from the first parameter, for example:
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/runtime/server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 export async function post({
   query,
@@ -204,7 +200,7 @@ export async function post({
 Custom types can also be used here:
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/runtime/server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 type IQuery = {
   // some types
@@ -256,9 +252,9 @@ export default () => {
 
 ## Extend BFF Function
 
-import ExtendBFF from "@site-docs-en/components/extend-bff-function"
+import ExtendBFF from '@site-docs-en/components/extend-bff-function';
 
-<ExtendBFF/>
+<ExtendBFF />
 
 ## Code Sharing