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

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

@@ -1,134 +0,0 @@
----
-title: Hook
----
-
-# Hook
-
-:::warning
-
-The Hook API has been deprecated. Please use the [new Custom Web Server](/guides/advanced-features/web-server) to handle page requests.
-
-:::
-
-Used to extend Modern.js built-in Web Server, all page requests are handled by these hooks.
-
-## Usage
-
-```ts
-import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (context, next) => {};
-export const afterRender: AfterRenderHook = (context, next) => {};
-```
-
-:::info
-Before using this API, please execute `pnpm run new` to create a new "Custom Web Server" source code directory.
-
-```bash
-pnpm run new
-? Please select the operation you want: Create Elements
-? Please select the type of element to create: New "Custom Web Server" source code directory
-```
-
-:::
-
-## Function Signature
-
-```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: {
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-};
-
-function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
-```
-
-different Hooks additionally provide different contexts. Currently Modern.js support `AfterMatch` and `AfterRender`.
-
-```ts
-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;
-  };
-};
-```
-
-### Input
-
-- `context`: Hook context.
-  - `response`: provides a series of methods to process the response.
-  - `request`: provides a series of methods to get request info.
-  - `router`: provides methods on routing.
-  - `template`: provides methods on content.
-- `next`: call next listener (not affect the server process, only current hook).
-
-## Example
-
-### Redirect
-
-Redirect to pages outside the site, for example to login page:
-
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.redirect('https://website.com/login', 302);
-};
-```
-
-### Rewrite
-
-Rewrite to pages of the current site, for example, the same route returns pages that are adapted to different UA:
-
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.rewrite('mobile');
-};
-```
-
-### HTML Inject
-
-Inject some HTML content to the page, such as scripts, page skeletons, etc.:
-
-```ts
-import type { AfterRender } from '@modern-js/runtime/server';
-
-export const afterRender: AfterRenderHook = (context, next) => {
-  ctx.template.prependBody('<div>Footer</div>');
-};
-```

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

@@ -1,113 +0,0 @@
----
-title: Middleware
----
-
-# Middleware
-
-:::warning
-
-Middleware has been deprecated. Please use the [new Custom Web Server](/guides/advanced-features/web-server) to handle page requests.
-
-:::
-
-Used to extend the built-in Web Server of Modern.js, unlike [Hook](/apis/app/runtime/web-server/hook), Middleware can directly operate Node's origin request and response, and can be extended using the framework plugin.
-
-
-## Usage
-
-```ts
-import { Middleware } from '@modern-js/runtime/server';
-
-export const middleware: Middleware = async (context, next) => {};
-export const middleware: Middleware[] = [
-  async (context, next) => {},
-  async (context, next) => {},
-];
-```
-
-:::info
-Before using this API, please execute `pnpm run new` to create a new "Custom Web Server" source code directory.
-
-```bash
-pnpm run new
-? Please select the operation you want: Create Element
-? Please select the type of element to create: New "Custom Web Server" source code directory
-```
-
-:::
-
-## Function Signature
-
-```ts
-type Middleware = (
-  context: MiddlewareContext,
-  next: NextFunction,
-) => Promise<void> | void;
-
-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: {
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-  source: {
-    req: IncomingMessage;
-    res: ServerResponse;
-  };
-};
-```
-
-### Input
-
-- `context`: Middleware context.
-  - `response`: provides a series of methods to process the response.
-  - `request`: provides a series of methods to get request info.
-  - `source`: provides Node.js native `req` and `res` object.
-- `next`: call next listener (not affect the server process, only current hook).
-
-:::warning
-The execution of the `next` function does not affect built-in processes, only controls whether the next middleware executes. Rendering processes are interrupted only when the response is written.
-:::
-
-## Example
-
-### Tracking
-
-```ts
-export const Middleware = () => async (ctx, next) => {
-  const start = Date.now();
-  ctx.source.res.once('finish', () => {
-    console.log(Date.now() - start);
-  });
-};
-```
-
-### Inject Tools & Data
-
-Modern.js provides `res.locals` to store local variables for the current request.
-
-```ts
-export const Middleware = () => async (ctx, next) => {
-  ctx.response.locals.id = 'Modern.js';
-  ctx.response.locals.rpc = createRpcInstance();
-};
-```

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

@@ -1,167 +0,0 @@
----
-title: Unstable Middleware
----
-
-# Unstable Middleware
-
-:::warning
-
-UnstableMiddleware has been deprecated. Please use the [new Custom Web Server](/guides/advanced-features/web-server) to handle page requests.
-
-:::
-
-Used to extend the built-in Web Server in Modern.js.
-UnstableMiddleware will replace [Middleware](/apis/app/runtime/web-server/middleware) in the future.
-
-
-## Usage
-
-```ts title="server/index.ts"
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-export const unstableMiddleware: UnstableMiddleware[] = [];
-```
-
-## Types
-
-**UnstableMiddleware**
-
-```ts
-type UnstableMiddleware<
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = (
-  c: UnstableMiddlewareContext<V>,
-  next: UnstableNext,
-) => Promise<void | Response>;
-```
-
-**UnstableMiddlewareContext**
-
-```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>;
-  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>;
-};
-```
-
-**UnstableNext**
-
-```ts
-type UnstableNext = () => Promise<void>;
-```
-
-## Examples
-
-### Web Server Timing
-
-```ts
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-const time: UnstableMiddleware = async (c, next) => {
-  const start = Date.now();
-
-  await next();
-
-  const end = Date.now();
-
-  console.log(`${end - start}`);
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [time];
-```
-
-### Injecting Server Data for DataLoader Consumption
-
-```ts title="shared/index.ts"
-export type Vars = {
-  message: string;
-};
-```
-
-```ts title="server/index.ts"
-import {
-  UnstableMiddleware,
-  UnstableMiddlewareContext,
-} from '@modern-js/runtime/server';
-import type { Vars } from '../shared/index';
-
-const setPayload: UnstableMiddlewaree<Vars> = async (
-  c: UnstableMiddlewareContext<Vars>,
-  next,
-) => {
-  c.set('message', 'facker');
-
-  await next();
-};
-
-export const unstableMiddleware: UnstableMiddleware<Vars>[] = [setPayload];
-```
-
-```ts title="src/routes/page.data.ts"
-import type { Payload } from '../../shared/index';
-import { LoaderFunctionArgs } from '@modern-js/runtime/router';
-
-export const loader = async ({ context }: LoaderFunctionArgs<Vars>) => {
-  const message = context?.get('message');
-
-  // ...
-};
-```
-
-### Redirect
-
-```ts
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-const auth: UnstableMiddleware = async (c, next) => {
-  const user = getUser(c.request);
-
-  if (!user) {
-    return c.redirect('/login');
-  }
-
-  await next();
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [auth];
-```
-
-### Modify Response
-
-```ts
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-const modifier: UnstableMiddleware = async (c, next) => {
-  await next();
-
-  const { response } = c;
-
-  const text = await response.text();
-
-  const newText = text.replace('<html>', `<html lang="${language}">`);
-
-  const newheaders = response.headers;
-  newheaders.set('x-custom-value', 'modern');
-
-  c.response = c.body(newText, {
-    status: response.status,
-    headers: newheaders,
-  });
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [modifier];
-```

package/docs/en/components/bff-proxy-path-rewrite.mdx

@@ -1,16 +0,0 @@
-Path rewriting can also be performed here, such as proxying the request sent to `localhost:8080/api/topics` to `https://cnodejs.org/api/v1/topics`.
-
-```js title="modern.server-runtime.config.js"
-import { defineConfig } from '@modern-js/app-tools/server';
-export default defineConfig({
-  bff: {
-    proxy: {
-      '/api': {
-        target: 'https://cnodejs.org',
-        pathRewrite: { '/api/topics': '/api/v1/topics' },
-        changeOrigin: true,
-      },
-    },
-  },
-});
-```

package/docs/en/components/bff-proxy-principle.mdx

@@ -1 +0,0 @@
-BFF Proxy uses the powerful [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware). For more advanced usage, please refer to its [documentation](https://github.com/chimurai/http-proxy-middleware#options).

package/docs/en/components/builder.mdx

@@ -1,3 +0,0 @@
-Refers to the build layer of Modern.js. The goal of Builder is to provide Modern.js users with out-of-the-box build capabilities and support seamless switching between webpack and Rspack.
-
-The previous version of Modern.js `MAJOR_VERSION.46.0` used `@modern-js/builder`, which was upgraded to [Rsbuild](https://rsbuild.rs/) starting from `MAJOR_VERSION.46.0`.

package/docs/en/components/create-bff-api-app.mdx

@@ -1,25 +0,0 @@
-1. run `@modern-js/create` command：
-
-```bash
-npx @modern-js/create@latest myapi
-```
-
-2. interactive Q & A interface to initialize the project based on the results, with initialization performed according to the default settings:
-
-```bash
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-```
-
-3. Execute the `new` command，enable BFF:
-
-```bash
-? Please select the operation you want to perform Enable optional features
-? Please select the feature to enable Enable "BFF"
-? Please select BFF type Framework mode
-```
-
-
-4. Execute【[Existing BFF-enabled Projects](/en/guides/advanced-features/bff/cross-project.html#existing-bff-enabled-projects)】to turn on the cross-project call switch.
-
-**Note:** When a project serves solely as a BFF producer, its runtime does not depend on the `/src` source directory. Removing the `/src` directory can help optimize the project's build efficiency.

package/docs/en/components/custom-router-micro-frontend.mdx

@@ -1,40 +0,0 @@
-```js title="src/App.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-
-import { RouterProvider, Route, createBrowserRouter, createRoutesFromElements, BrowserRouter, Link, Outlet } from '@modern-js/runtime/router';
-
-const AppLayout = () => (
-  <>
-    <div><Link to={'/table'}>Loading conventional routed sub-applications</Link></div>
-    <div><Link to={'/dashboard'}>Loading Self-Controlled Routing Sub-Applications</Link></div>
-    <div><Link to={'/'}>Uninstall a sub-application</Link></div>
-    <Outlet />
-  </>
-)
-
-export default () => {
-  const { apps, MApp, Table, Dashboard } = useModuleApps();
-
-  // If you are not using the MApp component, you need to use createBrowserRouter to create the route.
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        <Route key={'table'} path={'table/*'} element={<Table />} />
-        <Route key={'dashboard'} path={'dashboard/*'} element={<Dashboard />} />
-      </Route>
-    )
-  );
-
-  return (
-    // Approach 1: Use MApp to automatically load sub-applications based on the configured activeWhen parameter (this project is configured in modern.config.ts)
-    // <BrowserRouter>
-    //   <MApp />
-    // </BrowserRouter>
-
-    // Approach 2: Manually write Route components to load sub-applications, which is convenient for scenarios that require authentication and other pre-requisite operations
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-};
-```

package/docs/en/components/enable-micro-frontend.mdx

@@ -1,30 +0,0 @@
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { garfishPlugin } from '@modern-js/plugin-garfish';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-  },
-  plugins: [appTools(), garfishPlugin()],
-});
-
-```
-
-```ts title="src/modern.runtime.ts"
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
-export default defineRuntimeConfig({
-  masterApp: {
-    apps: [{
-      name: 'Table',
-      entry: 'http://localhost:8081',
-      // activeWhen: '/table'
-    }, {
-      name: 'Dashboard',
-      entry: 'http://localhost:8082'
-      // activeWhen: '/dashboard'
-    }]
-  },
-});
-```

package/docs/en/components/enableSwc.mdx

@@ -1,17 +0,0 @@
-First, you need to execute `pnpm run new` to enable the SWC compile:
-
-```bash
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable SWC Compile
-```
-
-After the installation, please register the SWC plugin in the `modern.config.ts` file, then the SWC compilation and compression will be enabled.
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { swcPlugin } from '@modern-js/plugin-swc';
-
-export default defineConfig({
-  plugins: [appTools(), swcPlugin()],
-});
-```

package/docs/en/components/global-proxy-config.mdx

@@ -1,85 +0,0 @@
-- **Type:** `string | Object`
-- **Default:** `null`
-
-This option is used to configure a global proxy based on [whistle](https://wproxy.org/whistle/) in the development environment, which can be used to view and modify HTTP/HTTPS requests, responses, and can also be used as a proxy server.
-
-### Register Plugin
-
-Before using this option, you need to install and register the `@modern-js/plugin-proxy` plugin:
-
-import { PackageManagerTabs } from '@theme';
-
-<PackageManagerTabs command="add @modern-js/plugin-proxy -D" />
-
-After the installation, please register the plugin in the `modern.config.ts` file:
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { proxyPlugin } from '@modern-js/plugin-proxy';
-
-export default defineConfig({
-  plugins: [appTools(), proxyPlugin()],
-});
-```
-
-### Object Type
-
-When the value of `dev.proxy` is object type, the `key` of the object corresponds to the matching `pattern`, and the `value` of the object corresponds to the matching `target`.
-
-Example:
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: {
-      'https://www.baidu.com': 'https://google.com.hk',
-      // Static files can be returned directly via the file protocol
-      'https://example.com/api': 'file://./data.json',
-    },
-  },
-});
-```
-
-Please refer to [whistle - Matching Patterns](https://wproxy.org/whistle/pattern.html) for detailed usage.
-
-### String Type
-
-When the value of `dev.proxy` is string type, it can be used to specify a separate proxy file, for example:
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: './proxy.js',
-  },
-});
-```
-
-```js title="proxy.js"
-module.exports = {
-  name: 'my-app',
-  rules: `
-    ^example.com:8080/api/***   http://localhost:3001/api/$
-  `,
-};
-```
-
-### Start Proxy
-
-Execute `dev`, when the prompt is as follows, the proxy server starts successfully:
-
-```bash
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-info      Starting proxy server.....
-success   Proxy server start on localhost:8899
-```
-
-Access the `localhost:8899` to view the Network and configure proxy rules on the UI interface:
-
-![proxy UI](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
-
-:::info
-The https agent automatically installs the certificate to obtain root privileges. Please enter the password as prompted. ** The password is only used when the certificate is trusted and will not be leaked or used for other links **.
-
-:::

package/docs/en/components/global-proxy.mdx

@@ -1,29 +0,0 @@
-:::warning
-`@modern-js/plugin-proxy` is no longer maintained and new versions will no longer be released. Please consider migrating to other proxy tools, such as [whistle](https://github.com/avwo/whistle).
-:::
-
-Modern.js provides an out-of-the-box global proxy plugin `@modern-js/plugin-proxy`, which is based on [whistle](https://github.com/avwo/whistle) and can be used to view and modify the requests and responses of HTTP/HTTPS, as well as be used as an HTTP proxy server.
-
-### Setting Proxy Rules
-
-After installing the proxy plugin and configuring the rules, run `pnpm run dev`. Modern.js will automatically enable the proxy server when the development server is started.
-
-Specific proxy rules can be set via the [`dev.proxy`](/configure/app/dev/proxy) or the `config/proxy.js` file.
-
-### Proxy Dashboard
-
-After installing the proxy plugin and configuring the proxy rules, run the `pnpm run dev` command:
-
-```bash
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-info      Starting proxy server.....
-success   Proxy server start on localhost:8899
-```
-
-You can see that the proxy server has started successfully in the console.
-
-Access `http://localhost:8899`, and you can set the rules through the dashboard.
-
-![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)

package/docs/en/components/package-manager.mdx

@@ -1,11 +0,0 @@
-### packageManager
-
-Question: Please select the package manager.
-
-Options:
-
-- pnpm -- pnpm
-
-- Yarn -- yarn
-
-- npm -- npm