@modern-js/main-doc 3.0.0-alpha.2 → 3.0.0

package/docs/en/apis/app/hooks/api/lambda.mdx

@@ -1,8 +1,8 @@
 ---
-title: lambda/*.[tj]s
+title: lambda/*.ts
 sidebar_position: 3
 ---
-# lambda/*.[tj]s
+# lambda/*.ts
 
 After enabling BFF, the files under the `lambda/` directory will be registered as BFF routes according to conventions.
 
@@ -10,4 +10,4 @@ After enabling BFF, the files under the `lambda/` directory will be registered a
 The files can be written in `js` or `ts` languages, but they must use `esm` syntax to export functions.
 :::
 
-For detailed information, refer to [BFF API Routes](/guides/advanced-features/bff/function.html#api-routes).
+For detailed information, refer to [BFF API Routes](/guides/advanced-features/bff/function.html#api-routes).

package/docs/en/apis/app/hooks/modern-config.mdx

@@ -1,8 +1,8 @@
 ---
-title: modern.config.[tj]s
+title: modern.config.ts
 sidebar_position: 8
 ---
-# modern.config.[tj]s
+# modern.config.ts
 
 The Modern.js configuration file. Through this file, you can personalize the configuration of various aspects of the current project.
 

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

@@ -1,9 +1,9 @@
 ---
-title: modern.server.[tj]s
+title: modern.server.ts
 sidebar_position: 1
 ---
 
-# modern.server.[tj]s
+# modern.server.ts
 
 This file extends the Modern.js Server. In this file, you can configure [Middleware](/guides/advanced-features/web-server.html#middleware), [RenderMiddleware](/guides/advanced-features/web-server.html#rendermiddleware), or [Plugin](/guides/advanced-features/web-server.html#plugin) for the Server that starts with the Modern.js project.
 

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

@@ -1,8 +1,8 @@
-# App.[tj]sx
+# App.tsx
 
 The entry identifier when using [Self-controlled Routing](/guides/concept/entries.html#self-controlled-routing) in the application.
 
-`App.[tj]sx` is not the actual application entry; Modern.js will automatically generate the real entry file, which is roughly as follows:
+`App.tsx` is not the actual application entry; Modern.js will automatically generate the real entry file, which is roughly as follows:
 
 ```js
 // runtime-global-context
@@ -26,5 +26,5 @@ render(<ModernRoot />, 'root');
 When `createRoot` is executed, it will retrieve the registered Global App and generate the actual React component.
 
 :::note
-In scenarios with multiple entry points, each entry can have its own independent `App.[jt]sx`. For more details, see [Entry Points](/guides/concept/entries).
+In scenarios with multiple entry points, each entry can have its own independent `App.tsx`. For more details, see [Entry Points](/guides/concept/entries).
 :::

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

@@ -1,15 +1,15 @@
 ---
-title: entry.[tj]s
+title: entry.ts
 sidebar_position: 4
 ---
 
-# entry.[tj]sx
+# entry.tsx
 
-Normally, the [`routes/`](/apis/app/hooks/src/routes.html) and [`App.[tj]sx`](/apis/app/hooks/src/app) hook files can meet our needs. When we need to add custom behavior before component rendering or take full control of the webpack packaging entry, we can create `entry.[tj]s` file in the src or entry directory. Here are two cases for discussion。
+Normally, the [`routes/`](/apis/app/hooks/src/routes.html) and [`App.tsx`](/apis/app/hooks/src/app) hook files can meet our needs. When we need to add custom behavior before component rendering or take full control of the Rspack packaging entry, we can create `entry.ts` file in the src or entry directory. Here are two cases for discussion。
 
 ## Add custom behavior before Render
 
-This is implemented in `src/entry.[tj]s` as follows:
+This is implemented in `src/entry.ts` as follows:
 
 ```js title=src/entry.tsx
 import { createRoot } from '@modern-js/runtime/react';
@@ -26,9 +26,9 @@ beforeRender().then(() => {
 });
 ```
 
-## Take full control of the webpack entry
+## Take full control of the Rspack entry
 
-When the project does not install the `@modern-js/runtime` dependency, `src/entry.[tj]sx?` is the real webpack packaging entry file, and you can directly organize the code like using create-react-app and other scaffolds:
+When the project does not install the `@modern-js/runtime` dependency, `src/entry.tsx?` is the real Rspack packaging entry file, and you can directly organize the code like using create-react-app and other scaffolds:
 
 ```js title=src/entry.jsx
 import React from 'react';

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

@@ -1,9 +1,9 @@
 ---
-title: entry.server.[tj]sx
+title: entry.server.tsx
 sidebar_position: 5
 ---
 
-# entry.server.[tj]sx
+# entry.server.tsx
 
 When the project initiates `server.ssr`, Modern.js generates a default Server-Side entry. The sample code is as follows:
 

package/docs/en/apis/app/hooks/src/modern.runtime.mdx

@@ -1,8 +1,8 @@
 ---
-title: modern.runtime.[tj]s
+title: modern.runtime.ts
 sidebar_position: 4
 ---
-# modern.runtime.[tj]s
+# modern.runtime.ts
 
 The Modern.js Runtime configuration file allows for personalized configuration of the Runtime capabilities for the current project.
 

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

@@ -8,7 +8,7 @@ The identifier for the entry point when the application uses [Conventional Routi
 
 Conventional routing uses `routes/` as the convention for the entry point and analyzes the files in the `src/routes` directory to obtain the client-side routing configuration.
 
-Any `layout.[tj]sx` and `page.[tj]sx` under `src/routes` will be used as the application's routes:
+Any `layout.tsx` and `page.tsx` under `src/routes` will be used as the application's routes:
 
 ```bash
 .

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

@@ -1,7 +1,7 @@
 ---
-title: '*.[server|node].[tj]sx'
+title: '*.[server|node].tsx'
 sidebar_position: 8
 ---
-# *.[server|node].[tj]sx
+# *.[server|node].tsx
 
 Used in the application project to place server-side code. When `*.tsx` and `*.[server|node].tsx` coexist, SSR will prefer to use the `*.[server|node].tsx` file instead of the `*.tsx` file when rendering on the server.

package/docs/en/apis/app/runtime/bff/use-hono-context.mdx

@@ -8,7 +8,7 @@ Used to obtain Hono context in an integrated BFF function.
 ## Usage
 
 ```ts
-import { useHonoContext } from '@modern-js/plugin-bff/server';
+import { useHonoContext } from '@modern-js/server-runtime';
 ```
 
 ## Function Signature
@@ -20,7 +20,7 @@ import { useHonoContext } from '@modern-js/plugin-bff/server';
 Developers can use `context` to obtain more request information, such as setting response headers:
 
 ```ts
-import { useHonoContext } from '@modern-js/plugin-bff/server';
+import { useHonoContext } from '@modern-js/server-runtime';
 
 export async function get() {
   const c = useHonoContext();

package/docs/en/apis/app/runtime/core/runtime-context.mdx

@@ -0,0 +1,160 @@
+---
+title: RuntimeContext
+---
+# RuntimeContext
+
+`RuntimeContext` is a React Context used to get Runtime context information in components. This Context can be accessed through React's `use` or `useContext` API.
+
+:::warning
+
+The `useRuntimeContext` Hook has been deprecated. Please use `use(RuntimeContext)` instead. `useRuntimeContext` is internally implemented as `useContext(RuntimeContext)`, while `use(RuntimeContext)` is the recommended new approach in React 19.
+
+:::
+
+## Usage
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export function App() {
+  const runtimeContext = use(RuntimeContext); // You can also use useContext(RuntimeContext)
+  return <div>Hello World</div>
+}
+```
+
+## Type Definition
+
+```ts
+type TRuntimeContext = {
+  initialData?: Record<string, unknown>;
+  isBrowser: boolean;
+  routes?: RouteObject[];
+  requestContext: RequestContext;
+  /**
+   * @deprecated Use `requestContext` instead
+   */
+  context: RequestContext;
+  [key: string]: unknown;
+};
+```
+
+### Property Description
+
+- `isBrowser`: Indicates whether the current runtime environment is a browser
+- `routes`: Route configuration information
+- `requestContext`: Request context, containing `request` and `response` objects
+- `context`: Deprecated, please use `requestContext` instead
+
+### RequestContext
+
+`RequestContext` is the type of the `requestContext` property, containing request and response related information:
+
+```ts
+type RequestContext = {
+  request: {
+    params: Record<string, string>;      // Route parameters
+    pathname: string;                     // Pathname
+    query: Record<string, string>;        // Query parameters
+    headers: IncomingHttpHeaders;         // Request headers
+    host: string;                         // Hostname
+    url: string;                          // Full URL
+    referer?: string;                     // Referrer page
+    userAgent?: string;                   // User agent
+    cookie?: string;                      // Cookie string
+    cookieMap?: Record<string, string>;   // Cookie map object
+  };
+  response: {
+    setHeader: (key: string, value: string) => void;  // Set response header (server-side only)
+    status: (code: number) => void;                   // Set status code (server-side only)
+    locals: Record<string, any>;                      // Local data
+  };
+};
+```
+
+**Notes**:
+
+- `response.setHeader` and `response.status` are only available on the server-side (SSR)
+- On the browser side, the `response` object may not contain these methods
+- The `request` object is available on both server and browser, but server-side information is more complete
+
+## Usage Examples
+
+### Distinguishing Runtime Environment
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const { context, isBrowser } = use(RuntimeContext);
+
+  if (isBrowser === true) {
+    // Browser-side execution logic
+    console.log('browser render')
+  } else {
+    // Server-side execution logic
+    // Note: Functions like logger need to be injected into context through Runtime plugins
+    console.log('server render')
+  }
+}
+```
+
+### Getting Request Context
+
+When SSR is enabled, isomorphic request context can be obtained in both Node environment and browser environment.
+
+The slight difference is that the Node environment also supports setting response headers, response codes, and provides Logger logging and Metrics tracking.
+
+:::tip
+
+When SSR is not enabled, only the information that can be obtained on the browser side is included.
+
+:::
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const runtimeContext = use(RuntimeContext);
+  const { request, response } = runtimeContext.requestContext || {};
+
+  // Access request information
+  const userAgent = request?.userAgent || request?.headers?.['user-agent'];
+  const url = request?.url;
+  const query = request?.query;
+  const params = request?.params;
+
+  // Server-side can set response headers
+  if (!runtimeContext.isBrowser && response) {
+    response.setHeader('X-Custom-Header', 'value');
+    response.status(200);
+  }
+
+  return (
+    <div>
+      <div>User Agent: {userAgent}</div>
+      <div>URL: {url}</div>
+      <div>Query: {JSON.stringify(query)}</div>
+    </div>
+  );
+}
+```
+
+### Accessing Injected Global Data
+
+Global data can be injected into `RuntimeContext` through the `onBeforeRender` hook of Runtime plugins:
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = use(RuntimeContext);
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+

package/docs/en/community/blog/2022-0708-updates.md

@@ -74,7 +74,7 @@ Reduck 作为 Modern.js 的第一方状态管理方案，发布 v1.1 版本，
 **新增命令**
 
 - [`upgrade`](https://modernjs.dev/v1/docs/apis/app/commands/upgrade)：自动升级 Modern.js 版本。功能同执行 `npx @modern-js/upgrade` 命令。
-- [`inspect`](https://modernjs.dev/v1/docs/apis/app/commands/inspect)：通过该命令可以输出当前项目使用的完整 webpack 配置。
+- [`inspect`](https://modernjs.dev/v1/docs/apis/app/commands/inspect)：通过该命令可以输出当前项目使用的完整 rspack 配置。
 - [`gen-release-note`](https://modernjs.dev/v1/docs/apis/module/commands/gen-release-note)：自动根据当前仓库的 [changesets](https://github.com/changesets/changesets) 信息生成发布日志。此外，我们提供了[包版本管理专题文档](https://modernjs.dev/v1/docs/guides/features/changesets/introduce)，方便大家更好的认识和使用 changesets 及相关功能。
 
 **新增配置**

package/docs/en/components/default-browserslist.mdx

@@ -0,0 +1,7 @@
+
+```yaml title=".browserslistrc"
+chrome >= 87
+edge >= 88
+firefox >= 78
+safari >= 14
+```

package/docs/en/components/enable-bff.mdx

@@ -25,7 +25,7 @@ pnpm add @modern-js/plugin-bff@<version>
 
 2. Configure `modern.config.ts`
 
-Import and add the BFF plugin in the `modern.config.[tj]s` file:
+Import and add the BFF plugin in the `modern.config.ts` file:
 
 ```ts title="modern.config.ts"
 import { defineConfig, appTools } from '@modern-js/app-tools';

package/docs/en/components/enable-ssg.mdx

@@ -26,7 +26,7 @@ pnpm add @modern-js/plugin-ssg@<version>
 
 2. Configure modern.config.ts
 
-Import and add the SSG plugin in the `modern.config.[tj]s` file, and configure `output.ssg`:
+Import and add the SSG plugin in the `modern.config.ts` file, and configure `output.ssg`:
 
 ```ts title="modern.config.ts"
 import { defineConfig, appTools } from '@modern-js/app-tools';

package/docs/en/components/extend-bff-function.mdx

@@ -1,3 +1,3 @@
-The standard BFF function writing method may not always meet your needs. For example, complex TS type requirements in business scenarios. EdenX provides a more powerful BFF function writing method.
+The standard BFF function writing method may not always meet your needs. For example, complex TS type requirements in business scenarios. Modern.js provides a more powerful BFF function writing method.
 
 For more details, please refer to - [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators).

package/docs/en/components/hono.mdx

@@ -3,7 +3,7 @@
 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/server';
+import { useHonoContext } from '@modern-js/server-runtime';
 
 export const get = async () => {
   const c = useHonoContext();
@@ -21,7 +21,8 @@ For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-hono-conte
 When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
 
 ```ts title="api/lambda/cookies.ts"
-import { Api, Get, useHonoContext } from '@modern-js/plugin-bff/server';
+import { Api, Get } from '@modern-js/plugin-bff/server';
+import { useHonoContext } from '@modern-js/server-runtime';
 
 // Helper function to parse Cookie string
 function parseCookies(

package/docs/en/components/ssr-monitor.mdx

@@ -1,3 +1,3 @@
-:::note
-Coming soon
+:::tip
+SSR monitoring has been integrated into the Monitors module, see [Monitors](/guides/advanced-features/server-monitor/monitors) for details.
 :::

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

@@ -96,7 +96,7 @@ const defaultOptions = {
   // - localhost
   // - 127.0.0.1
   // - [::1]
-  origin: defaultAllowedOrigins
+  origin: defaultAllowedOrigins,
 };
 ```
 
@@ -104,108 +104,25 @@ For more configuration options and detailed usage, please refer to the [Rsbuild
 
 ### proxy
 
-- **Type:** `Record<string, string> | Record<string, ProxyDetail>`
+- **Type:** `ProxyOptions[] | Record<string, string | ProxyOptions>`
 - **Default:** `undefined`
 
-Proxy requests to the specified service.
+Configure proxy rules for the dev server, and forward requests to the specified service.
 
 ```js
 export default {
   dev: {
     server: {
       proxy: {
-        '/api': 'http://localhost:3000',
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com/api',
       },
     },
   },
 };
 ```
 
-At this point, the /api/users request will be proxied to http://localhost:3000/api/users.
-
-If you don't want to pass /api, you can rewrite the request path through `pathRewrite`:
-
-```js
-export default {
-  dev: {
-    server: {
-      proxy: {
-        '/api': {
-          target: 'http://localhost:3000',
-          pathRewrite: { '^/api': '' },
-        },
-      },
-    },
-  },
-};
-```
-
-DevServer Proxy is implemented based on [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x). You can use all configuration items of http-proxy-middleware, see the documentation for details.
-
-The full type definition of DevServer Proxy is:
-
-```ts
-import type { Options as HttpProxyOptions } from 'http-proxy-middleware';
-
-type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
-
-type ProxyDetail = HttpProxyOptions & {
-  bypass?: (
-    req: IncomingMessage,
-    res: ServerResponse,
-    proxyOptions: ProxyOptions,
-  ) => string | undefined | null | false;
-  context?: Filter;
-};
-
-type ProxyOptions =
-  | Record<string, string>
-  | Record<string, ProxyDetail>
-  | ProxyDetail[]
-  | ProxyDetail;
-```
-
-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 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 method
-export default {
-  dev: {
-    server: {
-      proxy: {
-        '/api': {
-          target: 'http://localhost:3000',
-          bypass: function (req, res, proxyOptions) {
-            if (req.headers.accept.indexOf('html') !== -1) {
-              console.log('Skipping proxy for browser request.');
-              return '/index.html';
-            }
-          },
-        },
-      },
-    },
-  },
-};
-```
-
-```js
-// Proxy multiple paths to the same target
-export default {
-  dev: {
-    server: {
-      proxy: [
-        {
-          context: ['/auth', '/api'],
-          target: 'http://localhost:3000',
-        },
-      ],
-    },
-  },
-};
-```
+:::tip
+This option is the same as Rsbuild's `server.proxy` option, see [Rsbuild - server.proxy](https://v2.rsbuild.rs/config/server/proxy) for detailed usage.
+:::

package/docs/en/configure/app/output/assets-retry.mdx

@@ -78,4 +78,4 @@ export default {
 
 With the configuration above, if an asset fails to load from `cdn1.com`, requests will automatically fall back to `cdn2.com`. If `cdn2.com` also fails, the request will continue to `cdn3.com`.
 
-`assetsRetry` is implemented based on the Assets Retry plugin of Rsbuild and provides the same configuration options. You can refer to [Rsbuild - Assets Retry Plugin](https://rsbuild.rs/plugins/list/plugin-assets-retry#options) to understand all available configuration options.
+`assetsRetry` is implemented based on the Assets Retry plugin of Rsbuild and provides the same configuration options. You can refer to [Rsbuild - Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry) to understand all available configuration options.

package/docs/en/configure/app/source/alias-strategy.mdx

@@ -4,6 +4,10 @@ title: aliasStrategy
 
 # source.aliasStrategy
 
+:::warning Deprecation Warning
+`source.aliasStrategy` is deprecated, please use [resolve.aliasStrategy](/configure/app/resolve/alias-strategy) instead.
+:::
+
 - **Type:** `'prefer-tsconfig' | 'prefer-alias'`
 - **Default:** `'prefer-tsconfig'`
 

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

@@ -4,6 +4,10 @@ title: alias
 
 # source.alias
 
+:::warning Deprecation Warning
+`source.alias` is deprecated, please use [resolve.alias](/configure/app/resolve/alias) instead.
+:::
+
 - **Type:**
 
 ```ts

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

@@ -46,7 +46,7 @@ export default defineConfig({
 });
 ```
 
-By default, the configured entry is equivalent to `App.[jt]sx`, which means that the specified entry file **only needs to export the root component of the application**.
+By default, the configured entry is equivalent to `App.tsx`, which means that the specified entry file **only needs to export the root component of the application**.
 
 For example, the following directory structure:
 
@@ -102,7 +102,7 @@ export default defineConfig({
 
 ### 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 the entry you configured.
+By default, the configured entry is equivalent to `App.tsx`, and Modern.js will automatically generate an entry file to reference the entry you configured.
 
 If you want to disable the logic of Modern.js automatically generating entry files, you can set the `disableMount` property to `true`.