@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

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

@@ -6,27 +6,54 @@ sidebar_position: 16
 
 Modern.js encapsulates most server-side capabilities required by projects, typically eliminating the need for server-side development. However, in certain scenarios such as user authentication, request preprocessing, or adding page skeletons, custom server-side logic may still be necessary.
 
-## Starting a Custom Web Server
+To use the Custom Web Server in a Modern.js project, follow these steps:
 
-:::tip
-You must ensure that the Modern.js version is x.67.5 or above.
-:::
+1. Install `@modern-js/server-runtime` dependency
 
-Developers can execute the `pnpm run new` command in the project root directory to start the "Custom Web Server" feature:
+If the `@modern-js/server-runtime` dependency is not yet installed in your project, install it first:
 
 ```bash
-? Select operation: Create project element
-? Select element type: Create "Custom Web Server" source directory
+pnpm add @modern-js/server-runtime
+```
+
+:::tip Version Consistency
+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>
 ```
 
-After executing the command, a `server/modern.server.ts` file will be automatically created in the project directory, where you can write custom logic.
+:::
+
+2. Create the `server` directory and configuration file
+
+Create a `server/modern.server.ts` file in the project root directory:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // Middleware
+  renderMiddlewares: [], // Render Middleware
+  plugins: [], // Plugins
+  onError: () => {}, // Error handling
+});
+```
 
+After creating the file, you can write custom logic in this file.
 
 ## Capabilities of the Custom Web Server
 
 Modern.js's Web Server is based on Hono, and in the latest version of the Custom Web Server, we expose Hono's middleware capabilities, you can refer to [Hono API](https://hono.dev/docs/api/context) for more usage.
 
 In the `server/modern.server.ts` file, you can add the following configurations to extend the Server:
+
 - **Middleware**
 - **Render Middleware**
 - **Server-side Plugin**
@@ -51,7 +78,6 @@ export default defineServerConfig({
 });
 ```
 
-
 ### Type Definition
 
 `defineServerConfig` type definition is as follows:
@@ -61,22 +87,21 @@ import type { MiddlewareHandler } from 'hono';
 
 type MiddlewareOrder = 'pre' | 'post' | 'default';
 type MiddlewareObj = {
-    name: string;
-    path?: string;
-    method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
-    handler: MiddlewareHandler | MiddlewareHandler[];
-    before?: Array<MiddlewareObj['name']>;
-    order?: MiddlewareOrder;
+  name: string;
+  path?: string;
+  method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+  handler: MiddlewareHandler | MiddlewareHandler[];
+  before?: Array<MiddlewareObj['name']>;
+  order?: MiddlewareOrder;
 };
 type ServerConfig = {
-    middlewares?: MiddlewareObj[];
-    renderMiddlewares?: MiddlewareObj[];
-    plugins?: (ServerPlugin | ServerPluginLegacy)[];
-    onError?: (err: Error, c: Context) => Promise<any> | any;
-}
+  middlewares?: MiddlewareObj[];
+  renderMiddlewares?: MiddlewareObj[];
+  plugins?: ServerPlugin[];
+  onError?: (err: Error, c: Context) => Promise<any> | any;
+};
 ```
 
-
 ### Middleware
 
 Middleware supports executing custom logic before and after the **request handling** and **page routing** processes in Modern.js services.
@@ -89,7 +114,10 @@ If you only need to handle BFF API routes, you can determine whether a request i
 Usage is as follows:
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 export const handler: MiddlewareHandler = async (c, next) => {
   const monitors = c.get('monitors');
@@ -116,13 +144,15 @@ export default defineServerConfig({
 You must execute the `next` function to proceed with the subsequent Middleware.
 :::
 
-
 ### RenderMiddleware
 
 If you only need to handle the logic before and after page rendering, modern.js also provides rendering middleware, which can be used as follows:
 
 ```ts title="server/modern.server.ts"
-import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
 
 // Inject render performance metrics
 const renderTiming: MiddlewareHandler = async (c, next) => {
@@ -162,52 +192,46 @@ export default defineServerConfig({
 });
 ```
 
-
 ### Plugin
 
 Modern.js supports adding the aforementioned middleware and rendering middleware for the Server in custom plugins, which can be used as follows:
 
-
 ```ts title="server/plugins/server.ts"
-import type { ServerPluginLegacy } from '@modern-js/server-runtime';
+import type { ServerPlugin } from '@modern-js/server-runtime';
 
-export default (): ServerPluginLegacy => ({
+export default (): ServerPlugin => ({
   name: 'serverPlugin',
   setup(api) {
-    return {
-      prepare(serverConfig) {
-        const { middlewares, renderMiddlewares } = api.useAppContext();
-
-        // Inject server-side data for page dataLoader consumption
-        middlewares?.push({
-          name: 'server-plugin-middleware',
-          handler: async (c, next) => {
-            c.set('message', 'hi modern.js');
-            await next();
-            // ...
-          },
-        });
-
-        // redirect
-        renderMiddlewares?.push({
-          name: 'server-plugin-render-middleware',
-          handler: async (c, next) => {
-            const user = getUser(c.req);
-            if (!user) {
-              return c.redirect('/login');
-            }
-
-            await next();
-          },
-        });
-        return serverConfig;
-      },
-    };
+    api.onPrepare(() => {
+      const { middlewares, renderMiddlewares } = api.getServerContext();
+
+      // Inject server-side data for page dataLoader consumption
+      middlewares?.push({
+        name: 'server-plugin-middleware',
+        handler: async (c, next) => {
+          c.set('message', 'hi modern.js');
+          await next();
+          // ...
+        },
+      });
+
+      // redirect
+      renderMiddlewares?.push({
+        name: 'server-plugin-render-middleware',
+        handler: async (c, next) => {
+          const user = getUser(c.req);
+          if (!user) {
+            return c.redirect('/login');
+          }
+
+          await next();
+        },
+      });
+    });
   },
 });
 ```
 
-
 ```ts title="server/modern.server.ts"
 import { defineServerConfig } from '@modern-js/server-runtime';
 import serverPlugin from './plugins/serverPlugin';
@@ -217,7 +241,6 @@ export default defineServerConfig({
 });
 ```
 
-
 ```ts title="src/routes/page.data.ts"
 import { useHonoContext } from '@modern-js/server-runtime';
 import { defer } from '@modern-js/runtime/router';
@@ -229,10 +252,8 @@ export default () => {
 
   // ...
 };
-
 ```
 
-
 ### onError
 
 `onError` is a global error handling function used to capture and handle all uncaught errors in the Modern.js server. By customizing the `onError` function, developers can uniformly handle different types of errors, return custom error responses, and implement features such as error logging and error classification.
@@ -261,241 +282,3 @@ export default defineServerConfig({
   },
 });
 ```
-
-## Legacy API (Deprecated)
-
-:::warning
-The legacy API is compatible but no longer recommended. For extending server capabilities, please refer to [Custom Web Server](/guides/advanced-features/web-server.html#custom-web-server). For migration guidelines, see [Migrating to the New Version of Custom Web Server](/guides/advanced-features/web-server.html#migrate-to-the-new-version-of-custom-web-server).
-:::
-
-### Enable
-To enable the custom Web Server feature, follow these steps:
-1. Add `@modern-js/plugin-server`、`tsconfig-paths` and `ts-node` to `devDependencies` and install them.
-2. Add `server` to the `include` section of `tsconfig`.
-3. Register the `@modern-js/plugin-server` plugin in `modern.config.ts`.
-4. Create a `server/index.ts` file in the project directory, where you can write custom logic.
-
-### Unstable Middleware
-
-Modern.js supports adding rendering middleware to the Web Server, allowing custom logic execution before and after processing page routes.
-
-```ts title="server/index.ts"
-import {
-  UnstableMiddleware,
-  UnstableMiddlewareContext,
-} from '@Modern.js/runtime/server';
-
-const time: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
-  const start = Date.now();
-
-  await next();
-
-  const end = Date.now();
-
-  console.log(`dur=${end - start}`);
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [time];
-```
-
-
-### Hooks
-
-:::warning
-We recommend using UnstableMiddleware instead of Hooks.
-:::
-
-Modern.js provides Hooks to control specific logic in the Web Server. All page requests will pass through Hooks.
-
-Currently, two types of Hooks are available: `AfterMatch` and `AfterRender`. Developers can implement them in `server/index.ts` as follows:
-
-```ts
-import type {
-  AfterMatchHook,
-  AfterRenderHook,
-} from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (ctx, next) => {
-  next();
-};
-
-export const afterRender: AfterRenderHook = (ctx, next) => {
-  next();
-};
-```
-
-Best practices when using Hooks:
-
-1. Perform authorization checks in afterMatch.
-2. Handle Rewrite and Redirect in afterMatch.
-3. Inject HTML content in afterRender.
-
-
-
-## Migrate to the New Version of Custom Web Server
-
-### Migration Background
-
-Modern.js Server is continuously evolving to provide more powerful features. We have optimized the definition and usage of middleware and Server plugins.
-While the old custom Web Server approach is still compatible, we strongly recommend migrating according to this guide to fully leverage the advantages of the new version.
-
-### Migration Steps
-
-1. Upgrade Modern.js version to x.67.5 or above.
-2. Configure middleware or plugins in `server/modern.server.ts` according to the new definition method.
-3. Migrate the custom logic in `server/index.ts` to middleware or plugins, and update your code with reference to the differences between `Context` and `Next`.
-
-### Context Differences
-
-In the new version, the middleware handler type is Hono's `MiddlewareHandler`, meaning the `Context` type is `Hono Context`. The differences from the old custom Web Server's `Context` are as follows:
-
-
-#### UnstableMiddleware
-
-
-```ts
-type Body = ReadableStream | ArrayBuffer | string | null;
-
-type UnstableMiddlewareContext<
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = {
-  request: Request;
-  response: Response;
-  get: Get<V>;
-  set: Set<V>;
-  // Current Matched Routing Information
-  route: string;
-  header: (name: string, value: string, options?: { append?: boolean }) => void;
-  status: (code: number) => void;
-  redirect: (location: string, status?: number) => Response;
-  body: (data: Body, init?: ResponseInit) => Response;
-  html: (
-    data: string | Promise<string>,
-    init?: ResponseInit,
-  ) => Response | Promise<Response>;
-};
-```
-
-Differences between UnstableMiddleware Context and Hono Context:
-
-| UnstableMiddleware       | Hono                          | Description                                                                      |
-| :----------------------- | :---------------------------- | :------------------------------------------------------------------------ |
-| `c.request`              | `c.req.raw`                   | Refer to [HonoRequest raw](https://hono.dev/docs/api/request#raw) documentation         |
-| `c.response`             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation       |
-| `c.route`                | `c.get('route')`              | Get application context information.                                                          |
-| `loaderContext.get`      | `honoContext.get`             | After injecting data using `c.set`, consume in dataLoader: the old version uses `loaderContext.get`, refer to the new version in [Plugin](/guides/advanced-features/web-server.html#plugin) example    |
-
-
-#### Middleware
-
-```ts
-type MiddlewareContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-    locals: Record<string, any>;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-  source: {
-    req: IncomingMessage;
-    res: ServerResponse;
-  };
-};
-
-```
-
-Differences between Middleware `Context` and Hono `Context`:
-| UnstableMiddleware       | Hono                          | Description                                                                  |
-| :----------------------- | :---------------------------- | :--------------------------------------------------------------------------- |
-| `c.request.cookie`         | `c.req.cookie()`              | Refer to [Hono Cookie Helper](https://hono.dev/docs/helpers/cookie) documentation |
-| `c.request.pathname`       | `c.req.path`                  | Refer to [HonoRequest path](https://hono.dev/docs/api/request#path) documentation |
-| `c.request.url`            | -                             | Hono `c.req.url` provides the full request URL, calculate manually from URL |
-| `c.request.host`           | `c.req.header('Host')`        | Obtain host through header                                                  |
-| `c.request.query`          | `c.req.query()`               | Refer to [HonoRequest query](https://hono.dev/docs/api/request#query) documentation |
-| `c.request.headers`        | `c.req.header()`              | Refer to [HonoRequest header](https://hono.dev/docs/api/request#header) documentation |
-| `c.response.set`           | `c.res.headers.set`           | Example: `c.res.headers.set('custom-header', '1')`                          |
-| `c.response.status`        | `c.status`                    | Example: `c.status(201)`                                                    |
-| `c.response.cookies`       | `c.header`                    | Example: `c.header('Set-Cookie', 'user_id=123')`                            |
-| `c.response.raw`           | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation |
-
-#### Hook
-
-```ts
-type HookContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-};
-
-type AfterMatchContext = HookContext & {
-  router: {
-    redirect: (url: string, status: number) => void;
-    rewrite: (entry: string) => void;
-  };
-};
-
-type AfterRenderContext = {
-  template: {
-    get: () => string;
-    set: (html: string) => void;
-    prependHead: (fragment: string) => void;
-    appendHead: (fragment: string) => void;
-    prependBody: (fragment: string) => void;
-    appendBody: (fragment: string) => void;
-  };
-};
-```
-
-Hook Context is mostly consistent with Middleware Context, so we need to pay extra attention to the additional parts of different Hooks.
-
-| UnstableMiddleware       | Hono                          | Description                           |
-| :----------------------- | :---------------------------- | :------------------------------------ |
-| `router.redirect`        | `c.redirect`                  | Refer to [Hono Context redirect](https://hono.dev/docs/api/context#redirect) documentation      |
-| `router.rewrite`         | -                             | No corresponding capability provided at the moment                                                   |
-| template API             | `c.res`                       | Refer to [Hono Context res](https://hono.dev/docs/api/context#res) documentation               |
-
-
-### Differences in Next API
-
-In Middleware and Hooks, the render function executes even without invoking `next`.
-In the new design, subsequent Middleware will only execute if the `next` function is invoked.

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

@@ -1,5 +1,10 @@
 [
-  "routes",
+  {
+    "type": "dir",
+    "name": "routes",
+    "label": "Routes",
+    "collapsed": true
+  },
   {
     "type": "dir",
     "name": "data",

package/docs/en/guides/basic-features/css/css-in-js.mdx

@@ -1,23 +1,60 @@
 # Using CSS-in-JS
 
-CSS-in-JS is a technique that allows you to write CSS styles in JS files.
+CSS-in-JS is a technique that allows you to write CSS styles within JS files.
 
-Modern.js integrates the popular CSS-in-JS implementation library [styled-components](https://styled-components.com/), which uses the new JavaScript feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles. You can directly import the API of [styled-components](https://styled-components.com/) from `@modern-js/runtime/styled` for use.
+Modern.js supports the commonly used community CSS-in-JS library [styled-components](https://styled-components.com/), which uses JavaScript's new feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles.
 
-When you need to write a `div` component with an internal font color of red, you can implement it as follows:
+The Modern.js plugin `@modern-js/plugin-styled-components` provides support for styled-components and adds server-side rendering capability for styled-components. You can use styled-components by installing the `@modern-js/plugin-styled-components` plugin.
+
+## Using styled-components in Modern.js
+
+First, you need to install the `styled-components` plugin dependency and the `styled-components` library:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-styled-components styled-components -D',
+    yarn: 'yarn add @modern-js/plugin-styled-components styled-components -D',
+    pnpm: 'pnpm install @modern-js/plugin-styled-components styled-components -D',
+  }}
+/>
+
+Then configure the `styled-components` plugin in `modern.config.ts`:
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { styledComponentsPlugin } from '@modern-js/plugin-styled-components';
+
+export default defineConfig({
+  plugins: [
+    styledComponentsPlugin({
+      // ...
+      displayName: true,
+      minify: process.env.NODE_ENV === 'production',
+    }),
+  ],
+});
+```
+
+The configuration options of the styledComponentsPlugin plugin are the same as those of the [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) plugin. You can refer to the documentation of [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) for configuration.
+
+## Writing styles with styled-components
+
+When you need to write a `div` component with red text inside, you can implement it as follows:
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const RedDiv = styled.div`
   color: red;
 `;
 ```
 
-If you need to dynamically set component styles based on the component's `props`, for example, the `primary` property of `props` is `true`, the button color is white, otherwise it is red, you can implement the code as follows:
+When you need to dynamically set component styles based on the component's `props`, for example, when the `primary` attribute of `props` is `true`, the button's color is white, otherwise red, the implementation is as follows:
 
 ```js
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   color: ${props => (props.primary ? 'white' : 'red')};
@@ -25,10 +62,8 @@ const Button = styled.button`
 `;
 ```
 
-For more usage of styled-components, please refer to [styled-components official website](https://styled-components.com/).
-
-Modern.js integrates Babel's [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) plugin internally, and you can configure the plugin through [tools.styledComponents](/configure/app/tools/styled-components).
+For more usage of styled-components, please refer to the [styled-components official website](https://styled-components.com/).
 
-:::tip
-If you need to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx) and [Emotion](https://emotion.sh/), you need to install the corresponding dependencies first. For specific usage, please refer to the library's official website.
+:::tip Tip
+If you want to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/), etc., you need to install the corresponding dependencies first. Please refer to the official websites of the respective libraries for specific usage.
 :::

package/docs/en/guides/basic-features/css/css-modules.mdx

@@ -77,20 +77,6 @@ export default {
 };
 ```
 
-## Custom Class Names
-
-Customizing the class names generated by CSS Modules is also a commonly used function, you can use [output.cssModuleLocalIdentName](/configure/app/output/css-modules.html#cssmodulesexportlocalsconvention) to configure it.
-
-```ts
-export default {
-  output: {
-    cssModuleLocalIdentName: '[hash:base64:4]',
-  },
-};
-```
-
-If you need to customize other configs of CSS Modules, you can set them via [tools.cssLoader](/configure/app/tools/css-loader).
-
 ## Add Type Declaration
 
 When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:
@@ -181,9 +167,11 @@ For example, there are two files `src/index.ts` and `src/index.module.scss` unde
 import styles from './index.module.scss';
 
 export default () => {
-  <div>
-    <div className={styles.pageHeader}>Page Header</div>
-  </div>;
+  return (
+    <div>
+      <div className={styles.pageHeader}>Page Header</div>
+    </div>
+  );
 };
 ```
 

package/docs/en/guides/basic-features/css/css.mdx

@@ -18,14 +18,14 @@ You can also use Stylus in Modern.js by installing the Stylus plugin provided by
 
 Modern.js has built-in [PostCSS](https://postcss.org/) to transform CSS code.
 
-Please refer to [Rsbuild - Using PostCSS](https://rsbuild.rs/guide/basic/css-usage#using-postcss) for detailed usage.
+Please refer to [Rsbuild - Using PostCSS](https://rsbuild.rs/guide/styling/css-usage) for detailed usage.
 
 ## Using Lightning CSS
 
 Modern.js supports using [Lightning CSS](https://lightningcss.dev/) to convert CSS code. This feature can be turned on by configuring [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader).
 
-Please refer to [Rsbuild - Using Lightning CSS](https://rsbuild.rs/guide/basic/css-usage#lightning-css) for detailed usage.
+Please refer to [Rsbuild - Using Lightning CSS](https://rsbuild.rs/guide/styling/css-usage#lightning-css) for detailed usage.
 
 ## Using Uno CSS
 
-Please read the [Rsbuild - Using UnoCSS](https://rsbuild.rs/zh/guide/basic/unocss) for detailed usage.
+Please read the [Rsbuild - Using UnoCSS](https://rsbuild.rs/guide/styling/unocss) for detailed usage.