@modern-js/main-doc 2.8.0 → 2.9.0

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

@@ -0,0 +1,133 @@
+---
+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/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -0,0 +1,134 @@
+---
+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/docs/en/components/enable-bff.mdx

@@ -0,0 +1,31 @@
+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/docs/en/components/init-app.mdx

@@ -0,0 +1,43 @@
+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
+? Development Language: TS
+? Package Manager: 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/docs/en/components/init-rspack-app.mdx

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

package/docs/en/components/prerequisites.mdx

@@ -0,0 +1,18 @@
+### Node.js
+
+import NodeVersion from '@modern-js/builder-doc/docs/en/shared/nodeVersion.md';
+
+<NodeVersion />
+
+### pnpm
+
+It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
+
+```bash
+npm install -g pnpm@7
+```
+
+:::note
+Modern.js also supports dependency management with `yarn` and `npm`.
+
+:::

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

@@ -0,0 +1,13 @@
+---
+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/docs/en/configure/app/dev/before-start-url.mdx

@@ -0,0 +1,13 @@
+---
+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/docs/en/configure/app/dev/hmr.mdx

@@ -0,0 +1,13 @@
+---
+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/docs/en/configure/app/dev/host.mdx

@@ -0,0 +1,13 @@
+---
+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/docs/en/configure/app/dev/https.mdx

@@ -0,0 +1,13 @@
+---
+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 />

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

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

package/docs/en/configure/app/dev/progress-bar.mdx

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

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

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

package/docs/en/configure/app/experiments/lazy-compilation.mdx

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

package/docs/en/configure/app/html/app-icon.mdx

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

package/docs/en/configure/app/html/crossorigin.mdx

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

package/docs/en/configure/app/html/disable-html-folder.mdx

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

package/docs/en/configure/app/html/favicon-by-entries.mdx

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

package/docs/en/configure/app/html/favicon.mdx

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

package/docs/en/configure/app/html/inject-by-entries.mdx

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

package/docs/en/configure/app/html/inject.mdx

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

package/docs/en/configure/app/html/meta-by-entries.mdx

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

package/docs/en/configure/app/html/meta.mdx

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

package/docs/en/configure/app/html/mount-id.mdx

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

package/docs/en/configure/app/html/tags-by-entries.mdx

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

package/docs/en/configure/app/html/tags.mdx

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