npm - @modern-js/main-doc - Versions diffs - 2.1.0 → 2.3.0 - Mend

@modern-js/main-doc 2.1.0 → 2.3.0

Files changed (1299) hide show

package/zh/apis/app/runtime/utility/head.md DELETED Viewed

@@ -1,37 +0,0 @@
----
-title: Head
----
-用于给 `<head>` 元素内添加 html 元素（如 title、meta、script 等），支持 `SSR`。
-## 使用姿势
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-export default () => <Helmet>...</Helmet>;
-```
-## 示例
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-function IndexPage() {
-  return (
-    <div>
-      <Helmet>
-        <title>My page title</title>
-        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
-      </Helmet>
-      <p>Hello Modern.js!</p>
-    </div>
-  );
-}
-export default IndexPage;
-```
-## 更多用法
-详见 [react-helmet](https://github.com/nfl/react-helmet)。

package/zh/apis/app/runtime/utility/loadable.md DELETED Viewed

@@ -1,82 +0,0 @@
----
-title: loadable
----
-用于创建 Loadable 的组件。
-## 使用姿势
-```ts
-import loadable from '@modern-js/runtime/loadable';
-```
-## 函数签名
-```ts
-type Options = {
-  resolveComponent?: (
-    module: Module,
-    props: Props,
-  ) => React.ComponentType<Props>,
-  fallback?: JSX.Element;
-  ssr?: boolean;
-}
-function loadable(loadFn: Function, options?: Options) => LoadableComponent
-```
-### 参数
-#### loadFn
-用于加载组件。
-```ts
-import loadable from '@modern-js/runtime/loadable';
-const OtherComponent = loadable(() => import('./OtherComponent'));
-```
-#### options.resolveComponent
-类型：`(module: Module, props: Props) => React.ComponentType<Props>`
-`module` 为 `loadFn` 返回的组件，`props` 是 loadable 返回的组件接受的 props 参数。默认的话，我们认为 `import` 的文件都是默认导出 react 组件，这时候直接渲染该组件即可。但当组件是具名导出的，或者我们需要根据具体的 `props` 动态判断需要渲染哪个组件的时候，可以使用 `resolveComponent` 来实现。下面是一个示例：
-```ts title='component.js'
-export const Apple = () => 'Apple!';
-export const Orange = () => 'Orange!';
-```
-```ts title='loadable.js'
-const LoadableApple = loadable(() => import('./components'), {
-  resolveComponent: components => components.Apple,
-});
-const LoadableOrange = loadable(() => import('./components'), {
-  resolveComponent: components => components.Orange,
-});
-const LoadableFruit = loadable(() => import('./components'), {
-  resolveComponent: (components, props) => components[props.fruit],
-});
-```
-#### options.fallback
-是否在 loading 阶段显示 fallback 内容。
-#### options.ssr
-是否支持 SSR，默认值是 `true`。
-### 返回值
-#### LoadableComponent
-```ts
-type LoadableComponent<Props> = React.ComponentType<
-  Props & { fallback?: JSX.Element }
-> & {
-  preload(props?: Props): void;
-  load(props?: Props): Promise<React.ComponentType<Props>>;
-};
-```

package/zh/apis/app/runtime/web-server/hook.md DELETED Viewed

@@ -1,132 +0,0 @@
----
-title: Hook
----
-用于拓展 Modern.js 内置的 Web Server，非 BFF 请求会经过这些中 Hook 的处理。
-:::note
-更多内容可以查看[自定义 Web Server](/docs/guides/advanced-features/web-server)。
-:::
-## 使用姿势
-```ts
-import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
-export const afterMatch: AfterMatchHook = (context, next) => {};
-export const afterRender: AfterRenderHook = (context, next) => {};
-```
-:::info 自定义 Web Server
-使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Serve」源码目录。
-```bash
-pnpm run new
-? 请选择你想要的操作 创建工程元素
-? 新建「自定义 Web Server」源码目录
-```
-:::
-## 函数签名
-```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: {
-    url: string;
-    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;
-```
-另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AtferMatch` 和 `AfterRender` 两个 Hook。
-```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;
-  };
-};
-```
-### 参数
-- `context`：提供当前 Hook 上下文。
-  - `response`：提供一系列处理响应的操作
-  - `request`：提供一系列获取请求信息的操作
-  - `router`：提供对响应路由的快捷操作
-  - `template`：提供对响应内容的快捷操作
-- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
-## 示例
-### Redirect
-将页面重定向到站点外的页面，例如跳转到统一登录页：
-```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
-将页面重写到当前站点的其他页面，例如同一个路由根据 UA 返回适配不同端的页面：
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.rewrite('mobile');
-};
-```
-### HTML 内容注入
-为页面注入某些与渲染主体无关的 HTML 内容，如脚本、页面骨架等：
-```ts
-import type { AfterRender } from '@modern-js/runtime/server';
-export const afterRender: AfterRenderHook = (context, next) => {
-  ctx.template.prependBody('<div>Footer</div>');
-};
-```

package/zh/apis/app/runtime/web-server/middleware.md DELETED Viewed

@@ -1,109 +0,0 @@
----
-title: Middleware
----
-用于拓展 Modern.js 内置的 Web Server，只有 SSR 请求会经过这些中间件。
-与 [Hook](/docs/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以使用 Server 运行时框架拓展。
-:::note
-更多内容可以查看[自定义 Web Server](/docs/guides/advanced-features/web-server)。
-:::
-## 使用姿势
-```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 自定义 Web Server
-使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Server」源码目录。
-```bash
-pnpm run new
-? 请选择你想要的操作 创建工程元素
-? 新建「自定义 Web Server」源码目录
-```
-:::
-## 函数签名
-```ts
-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: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-  source: {
-    req: IncomingMessage;
-    res: ServerResponse;
-  };
-};
-type RequestHandler = (
-  context: Context,
-  next: NextFunction,
-) => Promise<void> | void;
-```
-### 参数
-- `context`：提供当前 Hook 上下文。
-  - `response`：提供一系列处理响应的操作
-  - `request`：提供一系列获取请求信息的操作
-  - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
-- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
-## 示例
-### 服务端耗时打点
-```ts
-export const Middleware = () => async (ctx, next) => {
-  const start = Date.now();
-  ctx.res.once('finish', () => {
-    console.log(Date.now() - start);
-  });
-};
-```
-### 注入服务端工具 & 数据
-Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量。
-```ts
-export const Middleware = () => async (ctx, next) => {
-  ctx.res.locals.id = 'Modern.js';
-  ctx.res.locals.rpc = createRpcInstance();
-});
-```

package/zh/apis/monorepo/commands/bump.md DELETED Viewed

@@ -1,42 +0,0 @@
----
-sidebar_position: 4
----
-```bash
-Usage: modern bump [options]
-使用变更集自动更新发布版本和变更日志
-Options:
-  --canary       创建一个预发布版本进行测试 (default: false)
-  --preid <tag>  在对预发布版本进行版本控制时指定标识符 (default: "next")
-  --snapshot     创建一个特殊版本进行测试 (default: false)
-  -h, --help     display help for command
-```
-:::info 注
-`bump` 命令执行之前需要提前执行 [`change`](/docs/apis/monorepo/commands/change) 命令添加 changeset。
-:::
-按 changeset 记录修改 `package.json` 中的版本号， 同时生成 `CHANGELOG.md`：
-```bash
-npx modern bump
-🦋  All files have been updated. Review them and commit at your leisure
-```
-`CHANGELOG.md` 示例内容如下：
-```md
-# package-a
-## 0.1.1
-### Patch Changes
-- test publish
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />

package/zh/apis/monorepo/commands/change.md DELETED Viewed

@@ -1,59 +0,0 @@
----
-sidebar_position: 2
----
-```bash
-Usage: modern change [options]
-创建变更集
-Options:
-  --empty     创建空变更集 (default: false)
-  --open      使用编辑器中打开创建的变更集 (default: false)
-  -h, --help  display help for command
-```
-:::info 注
-[`change`](/docs/apis/monorepo/commands/change)、[`pre`](/docs/apis/monorepo/commands/pre)、[`bump`](/docs/apis/monorepo/commands/bump)、[`release`](/docs/apis/monorepo/commands/release) 命令集成了工具 [`changesets`](https://github.com/atlassian/changesets) 管理版本变更和 Changelog。
-:::
-`modern change` 命令添加 changeset：
-```bash
-$ npx modern change
-🦋  Which packages would you like to include? · package-a, package-b
-🦋  Which packages should have a major bump? · No items were selected
-🦋  Which packages should have a minor bump? · No items were selected
-🦋  The following packages will be patch bumped:
-🦋  package-a@0.1.0
-🦋  package-b@0.1.0
-🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
-🦋  Summary · test publish
-🦋  === Releasing the following packages ===
-🦋  [Patch]
-🦋    package-a, package-b
-🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
-🦋  ║                                                      ========= NOTE ========                                                       ║
-🦋  ║All dependents of these packages that will be incompatible with the new version will be patch bumped when this changeset is applied.║
-🦋  ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
-🦋  Is this your desired changeset? (Y/n) · true
-🦋  Changeset added! - you can now commit it
-🦋
-🦋  If you want to modify or expand on the changeset summary, you can find it here
-🦋  info /xxxx/monorepo/.changeset/long-lizards-talk.md
-```
-上面我们给 `package-a` 和 `package-b` 都选择了 `patch` 变更，具体的变更信息在 monorepo 根目录下的 `.changeset/long-lizards-talk.md` 中:
-```md
----
-'package-a': patch
-'package-b': patch
----
-test publish
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />

package/zh/apis/monorepo/commands/clear.md DELETED Viewed

@@ -1,27 +0,0 @@
----
-sidebar_position: 8
----
-```bash
-Usage: modern clear [options]
-clear project dirs
-Options:
-  --remove-dirs [dirs...]  remove dirs, default is node_modules
-  -h, --help               display help for command
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />
-默认对 Monorepo 以及 Monorepo 子项目的 `node_modules` 进行清理。
-可以通过参数 `--remove-dirs` 来指定要删除的目录，例如执行：
-```bash
-$ npx modern clear --remove-dirs dist
-```
-则会清理所有 Monorepo 子项目的 `dist` 目录。

package/zh/apis/monorepo/commands/deploy.md DELETED Viewed

@@ -1,39 +0,0 @@
----
-sidebar_position: 7
----
-```bash
-Usage: modern deploy [options]
-deploy project
-Options:
-  -p, --path [path]  Specify the path of the product output (default: "output")
-  -h, --help         display help for command
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />
-对指定的项目进行部署，会通过指定项目分析其依赖的 Monorepo 下的子项目。
-在执行命令之后，会首先生成 `output` 目录，在目录当中包含了指定部署的项目以及其依赖的子项目，形成一个最小集合的 Monorepo。
-:::info 补充信息
-`output` 目录是默认目录，可以通过 `-p` 参数进行自定义。
-:::
-然后会在 `output` 目录下进行依赖的安装以及必要文件的复制。
-最后当依赖安装完成后，便完成了对指定项目的部署任务。
-例如部署项目名称为 `app` 的应用，则可以执行：
-```
-pnpm deploy app
-```
-:::info 补充信息
-其中 `app` 为项目的 `package.json` 的 `name` 值。
-:::

package/zh/apis/monorepo/commands/gen-release-note.md DELETED Viewed

@@ -1,34 +0,0 @@
----
-sidebar_position: 9
----
-```bash
-Usage: modern gen-release-note [options]
-根据当前仓库 changeset 文件生成 Release Note
-Options:
-  --repo <repo>      仓库名称，用于生成 Pull Request 链接， 例如： modern-js-dev/modern.js
-  --custom <cumtom>  自定义 Release Note 生成函数
-  -h, --help         display help for command
-```
-根据当前仓库的 changeset 信息自动生成 Release Note。
-:::warning 注意
-需要在 bump 命令之前执行。
-:::
-```markdown
-## Features:
-[[#1160](https://github.com/modern-js-dev/modern.js/pull/1160)] export ExecaError type
-## Bug Fix:
-[[#1264](https://github.com/modern-js-dev/modern.js/pull/1264)] fix: conventional router app use App.init not work
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />

package/zh/apis/monorepo/commands/lint.md DELETED Viewed

@@ -1,21 +0,0 @@
----
-sidebar_position: 6
----
-```bash
-Usage: modern lint [options] [...files]
-lint and fix source files
-Options:
-  --no-fix    disable auto fix source file
-  -h, --help  display help for command
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />
-运行 `ESLint` 检查 monorepo 中代码语法情况， 通长情况下，我们只需要在 `git commit` 阶段通过 `lint-staged` 检查本次提交修改的部分代码。
-- `--no-fix` 参数设置后可以关闭自动修复 lint 错误代码的能力。

package/zh/apis/monorepo/commands/new.md DELETED Viewed

@@ -1,41 +0,0 @@
----
-sidebar_position: 1
----
-```bash
-Usage: modern new [options]
-Monorepo 创建子项目
-Options:
-  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
-  -c, --config <config>  生成器运行默认配置(JSON 字符串)
-  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
-  --registry             生成器运行过程中定制 npm Registry
-  -h, --help             display help for command
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />
-`modern new` 命令在 monorepo 中可以用来添加应用工程和可复用的模块：
-```bash
-$ modern new
-? 请选择你想创建的工程类型 (Use arrow keys)
-❯ 应用
-  应用（测试）
-  模块
-  模块（内部）
-```
-应用工程默认会添加到 `apps` 目录， 测试应用会添加到 `examples` 目录，公共模块默认会添加到 `packages` 目录， 内部模块默认会添加到 `features` 目录。
-内部模块在 monorepo 的应用里面使用时，可以无需构建直接使用源码。
-:::caution 注意
-`--config` 参数对应参数值需要使用 JSON 字符串。
-pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
-:::

package/zh/apis/monorepo/commands/pre.md DELETED Viewed

@@ -1,68 +0,0 @@
----
-sidebar_position: 3
----
-```bash
-Usage: modern pre [options] <enter|exit> [tag]
-进入和退出预发布模式
-Options:
-  -h, --help  display help for command
-```
-import CommandTip from '@site-docs/components/command-tip.md'
-<CommandTip />
-可以使用 `modern pre` 命令在正式发布前[预发布](https://github.com/atlassian/changesets/blob/main/docs/prereleases.md)一个版本。
-首先 `modern pre enter <tag>` 进入预发布模式:
-```bash
-$ npx modern pre enter next
-🦋  success Entered pre mode with tag next
-🦋  info Run `changeset version` to version packages with prerelease versions
-```
-之后通过 `modern change` 命令添加 changeset:
-```bash
-$ npx modern change
-🦋  Which packages would you like to include? · package-a, package-b
-🦋  Which packages should have a major bump? · No items were selected
-🦋  Which packages should have a minor bump? · No items were selected
-🦋  The following packages will be patch bumped:
-🦋  package-a@0.1.1
-🦋  package-b@0.1.1
-🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
-🦋  Summary · test pre publish
-🦋  === Releasing the following packages ===
-🦋  [Patch]
-🦋    package-a, package-b
-🦋  ╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
-🦋  ║                                                      ========= NOTE ========                                                       ║
-🦋  ║All dependents of these packages that will be incompatible with the new version will be patch bumped when this changeset is applied.║
-🦋  ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
-🦋  Is this your desired changeset? (Y/n) · true
-🦋  Changeset added! - you can now commit it
-🦋
-🦋  If you want to modify or expand on the changeset summary, you can find it here
-🦋  info /xxxxxx/monorepo/.changeset/beige-paws-rule.md
-```
-接着可以使用 `modern bump` 命令更新具体的版本号：
-```bash
-$ npx modern bump
-🦋  warn ===============================IMPORTANT!===============================
-🦋  warn You are in prerelease mode
-🦋  warn If you meant to do a normal release you should revert these changes and run `changeset pre exit`
-🦋  warn You can then run `changeset version` again to do a normal release
-🦋  warn ----------------------------------------------------------------------
-🦋  All files have been updated. Review them and commit at your leisure
-```
-可以看到 `package-a` 和 `package-b` 的 `package.json` 中版本号均已更新到 `0.1.2-next.0`。
-提交完变更之后，我们可以通过 `modern pre exit` 命令退出预发布模式。