@modern-js/main-doc 2.8.0 → 2.10.0

package/en/apis/app/runtime/router/router.mdx

@@ -1,262 +0,0 @@
----
-title: router
-sidebar_position: 1
----
-# router
-
-:::info
-The router solution based on [react-router 6](https://reactrouter.com/).
-
-:::
-
-## hooks
-
-### useNavigate
-
-```ts
-declare function useNavigate(): NavigateFunction;
-
-interface NavigateFunction {
-  (
-    to: To,
-    options?: {
-      replace?: boolean;
-      state?: any;
-      relative?: RelativeRoutingType;
-    },
-  ): void;
-  (delta: number): void;
-}
-```
-
-The `useNavigate` hook returns a function that lets you navigate programmatically.
-
-```tsx
-import { useNavigate } from '@modern-js/runtime/router';
-
-export function HomeButton() {
-  let navigate = useNavigate();
-
-  function handleClick() {
-    navigate('/home');
-  }
-
-  return (
-    <button type="button" onClick={handleClick}>
-      Go home
-    </button>
-  );
-}
-```
-
-### useLocation
-
-```ts
-declare function useLocation(): Location;
-
-interface Location extends Path {
-  state: unknown;
-  key: Key;
-}
-```
-
-The `useLocation` hook returns the current [location](https://reactrouter.com/web/api/location) object. A new location object would be returned whenever the current location changes.
-
-```ts
-import { useLocation } from "@modern-js/runtime/router";
-
-function usePageViews() {
-  let location = useLocation();
-  React.useEffect(() => {
-    ga.send(["pageview", location.pathname]);
-  }, [location]);
-}
-
-function App() {
-  usePageViews();
-  return (
-    //...
-  );
-}
-```
-
-### useParams
-
-```ts
-declare function useParams<K extends string = string>(): Readonly<Params<K>>;
-```
-
-The `useParams` hook returns an object of key/value pairs of the dynamic params from the current URL that were matched by the `<Route path>`.
-
-```tsx
-import { Routes, Route, useParams } from '@modern-js/runtime/router';
-
-function BlogPost() {
-  const { slug } = useParams();
-  return <div>Now showing post {slug}</div>;
-}
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/" element={<div>home</div>} />
-      <Route path="/blog/:slug" element={<BlogPost />} />
-    </Routes>
-  );
-}
-```
-
-## Components
-
-### Link
-
-```ts
-declare function Link(props: LinkProps): React.ReactElement;
-
-interface LinkProps
-  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
-  replace?: boolean;
-  state?: any;
-  to: To;
-  reloadDocument?: boolean;
-}
-
-type To = string | Partial<Path>;
-```
-
-A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it.
-
-```ts
-<Link to="/about">About</Link>
-```
-
-### NavLink
-
-```ts
-declare function NavLink(props: NavLinkProps): React.ReactElement;
-
-interface NavLinkProps
-  extends Omit<LinkProps, 'className' | 'style' | 'children'> {
-  caseSensitive?: boolean;
-  children?:
-    | React.ReactNode
-    | ((props: { isActive: boolean }) => React.ReactNode);
-  className?: string | ((props: { isActive: boolean }) => string | undefined);
-  end?: boolean;
-  style?:
-    | React.CSSProperties
-    | ((props: { isActive: boolean }) => React.CSSProperties);
-}
-```
-
-A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active".
-
-### Outlet
-
-```ts
-interface OutletProps {
-  context?: unknown;
-}
-declare function Outlet(props: OutletProps): React.ReactElement | null;
-```
-
-An `<Outlet>` should be used in parent route elements to render their child route elements. This allows nested UI to show up when child routes are rendered.
-
-```tsx
-function Dashboard() {
-  return (
-    <div>
-      <h1>Dashboard</h1>
-
-      {/* This element will render either <DashboardMessages> when the URL is
-          "/messages", <DashboardTasks> at "/tasks", or null if it is "/"
-      */}
-      <Outlet />
-    </div>
-  );
-}
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/" element={<Dashboard />}>
-        <Route path="messages" element={<DashboardMessages />} />
-        <Route path="tasks" element={<DashboardTasks />} />
-      </Route>
-    </Routes>
-  );
-}
-```
-
-### Route
-
-```ts
-interface RouteObject {
-  path?: string;
-  index?: boolean;
-  children?: React.ReactNode;
-  caseSensitive?: boolean;
-  id?: string;
-  loader?: LoaderFunction;
-  action?: ActionFunction;
-  element?: React.ReactNode | null;
-  errorElement?: React.ReactNode | null;
-  handle?: RouteObject['handle'];
-  shouldRevalidate?: ShouldRevalidateFunction;
-}
-```
-
-`Route` represents the route information. A `Route` object couples URL segments to components, data loading and data mutations.
-
-`Route` can be used as a plain object, passing to the router creation functions：
-
-```ts
-const router = createBrowserRouter([
-  {
-    // it renders this element
-    element: <Team />,
-
-    // when the URL matches this segment
-    path: 'teams/:teamId',
-
-    // with this data loaded before rendering
-    loader: async ({ request, params }) => {
-      return fetch(`/fake/api/teams/${params.teamId}.json`, {
-        signal: request.signal,
-      });
-    },
-
-    // performing this mutation when data is submitted to it
-    action: async ({ request }) => {
-      return updateFakeTeam(await request.formData());
-    },
-
-    // and renders this element in case something went wrong
-    errorElement: <ErrorBoundary />,
-  },
-]);
-```
-
-You can also declare your routes with JSX and `createRoutesFromElements`, the props to the element are identical to the properties of the route objects:
-
-```ts
-const router = createBrowserRouter(
-  createRoutesFromElements(
-    <Route
-      element={<Team />}
-      path="teams/:teamId"
-      loader={async ({ params }) => {
-        return fetch(`/fake/api/teams/${params.teamId}.json`);
-      }}
-      action={async ({ request }) => {
-        return updateFakeTeam(await request.formData());
-      }}
-      errorElement={<ErrorBoundary />}
-    />,
-  ),
-);
-```
-
-## More
-
-You can access to [React Router](https://reactrouter.com/) to get the full API information.

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

@@ -1,133 +0,0 @@
----
-title: Hook
----
-# Hook
-
-Used to extend Modern.js built-in Web Server, all page requests are handled by these hooks.
-
-:::note
-For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
-
-:::
-
-## 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
-? Action Create project element
-? New "Custom Web Server" source code directory
-```
-
-:::
-
-## Function Signature
-
-```ts
-type HookContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => 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/en/apis/app/runtime/web-server/middleware.mdx

@@ -1,134 +0,0 @@
----
-title: Middleware
----
-# Middleware
-
-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.
-
-:::note
-For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
-
-:::
-
-## 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
-? Action Create project element
-? 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;
-    cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
-      clear: () => void;
-      apply: () => 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.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.res.locals.id = 'Modern.js';
-  ctx.res.locals.rpc = createRpcInstance();
-};
-```
-
-### Framework Extension
-
-Middleware can also use runtime framework extensions like BFF.
-
-When using framework runtime extensions, type information is exported from `@modern-js/runtime/{namespace}`. Middleware can use framework syntax, such as framework middleware writing, the following is pseudo-code:
-
-```ts
-import { SomeType } from '@modern-js/runtime/{namespace}';
-
-export const middleware: SomeType = (ctx, next) => {
-  console.log(ctx.url);
-  next();
-};
-```
-
-By default, the framework extension capability of Web Server is turned off after installing the framework extension plug-in. If you want to use the framework extension, you can turn it on through ['server.enableFrameworkExt'](/configure/app/server/enable-framework-ext.html).
-
-
-:::info
-The type name exported by the framework extension may not 'Middleware', but is named by the framework extension plugin.
-:::

package/en/components/enable-bff.mdx

@@ -1,31 +0,0 @@
-1. Execute `pnpm new` and select "Enable BFF"
-2. Add the following code to `modern.config.[tj]s` according to the chosen runtime framework：
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-<Tabs>
-  <TabItem value="express" label="Express.js" default>
-
-```ts title="edenx.config.ts"
-import expressPlugin from '@modern-js/plugin-express';
-import bffPlugin from '@modern-js/plugin-bff';
-
-export default defineConfig({
-  plugins: [expressPlugin(), bffPlugin()],
-});
-```
-
-  </TabItem>
-  <TabItem value="koa" label="Koa.js">
-
-```ts title="edenx.config.ts"
-import koaPlugin from '@modern-js/plugin-koa';
-import bffPlugin from '@modern-js/plugin-bff';
-
-export default defineConfig({
-  plugins: [koaPlugin(), bffPlugin()],
-});
-```
-
-  </TabItem>
-</Tabs>

package/en/components/init-app.mdx

@@ -1,43 +0,0 @@
-Modern.js generator will provide an interactive Q & A interface, initialization items according to the result, according to the default selection:
-
-```bash
-? Please select the solution you want to create: Web App Solution
-? Development Language: TS
-? Package Management Tool: pnpm
-```
-
-After create the project, Modern.js automatically installs dependency and creates a git repository.
-
-```bash
-[INFO] dependencies are automatically installed
-[INFO] git repository has been automatically created
-[INFO] Success！
-You can run the following command in the directory of the new project：
-pnpm run dev          # Run and debug the project according to the requirements of the development environment
-pnpm run build        # Build the project according to the requirements of the product environment
-pnpm run serve        # Run the project according to the requirements of the product environment
-pnpm run lint         # Check and fix all codes
-pnpm run new          # Create more project elements, such as application portals
-```
-
-:::note
-In addition to working during project initialization, the Modern.js generator can also generate modules of the project in subsequent development, which is not thrown away as soon as it is used.
-
-:::
-
-Now, the project structure is as follows:
-
-```
-.
-├── src
-│   ├── modern-app-env.d.ts
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── README.md
-└── tsconfig.json
-```

package/en/components/init-rspack-app.mdx

@@ -1,7 +0,0 @@
-```bash
-$ npx @modern-js/create myapp
-? Please select the solution you want to create: Web App Solution
-? Development Language: TS
-? Package Management Tool: pnpm
-? Build Tools: Rspack
-```

package/en/components/prerequisites.mdx

@@ -1,20 +0,0 @@
-### Node.js
-
-Requires [Node.js LTS] (https://github.com/nodejs/Release) and makes sure the Node version is greater than or equal to v16.18.1.
-
-Modern.js recommend installing [nvm](https://github.com/nvm-sh/nvm#install--update-script) in the development environment and integrating [script to automatically switch node versions](https://github.com/nvm-sh/nvm#deeper-shell-integration) in the shell.
-
-Then whenever there is a `.nvmrc` file with `lts/gallium` in the root directory of the repository, entering the repository will automatically install or switch to the correct Node.js version.
-
-### pnpm
-
-It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
-
-```bash
-npm install -g pnpm
-```
-
-:::note
-Modern.js also supports dependency management with `yarn` and `npm`.
-
-:::

package/en/configure/app/dev/asset-prefix.mdx

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

package/en/configure/app/dev/before-start-url.mdx

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

package/en/configure/app/dev/hmr.mdx

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

package/en/configure/app/dev/host.mdx

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

package/en/configure/app/dev/https.mdx

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