@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/apis/app/runtime/utility/loadable/loadable_.md

@@ -0,0 +1,110 @@
+---
+title: loadable
+sidebar_position: 1
+---
+
+:::info 补充信息
+用于创建 `loadable 的组件`。
+:::
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+```
+
+## API
+
+```ts
+<Props>(
+  loadFn: Function,
+  options?: {
+    resolveComponent?: (
+      module: Module,
+      props: Props,
+    ) => React.ComponentType<Props>,
+    fallback?: JSX.Element;
+    ssr?: boolean;
+  }
+) => LoadableComponent
+```
+
+### loadFn
+
+类型：`function`
+
+用于加载组件。
+
+```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
+
+类型：`JSX.Element`
+
+在 loading 阶段显示 fallback 内容。
+
+### options.ssr
+
+类型：`boolean`
+
+默认值：`true`
+
+如果是 `false`，则该组件不会再服务端渲染阶段处理，即不支持 ssr，默认值是 `true`。
+
+### LoadableComponent（返回值类型）
+
+[loadableComponent](./loadable-component.md)。
+
+## loadable.lib
+
+创建一个 `loadable 的库`。
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+const Moment = loadable.lib(() => import('moment'))
+```
+
+```ts
+<Props>(
+  loadFn: Function,
+  options?: {
+    resolveComponent?: any,
+    fallback?: any;
+    ssr?: boolean;
+  }
+) => LoadableLibrary
+```
+
+### options
+
+同 [options](#optionsresolvecomponent)。
+
+### LoadableLibrary （返回值类型）
+
+移架 [LoadableLibrary](./loadable-library.md)。
+

package/zh/apis/app/runtime/web-server/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Web Server API",
+  "position": 5
+}

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

@@ -0,0 +1,121 @@
+---
+sidebar_position: 3
+---
+
+# hook
+
+:::info 补充信息
+用于给 Web Server 添加中间件，发送给 Web Server 的请求会经过这些中间件的处理。
+```ts
+import { hook } from '@modern-js/runtime/server';
+```
+:::
+
+## API
+
+`hook(options) => void`
+
+### 参数
+
+- options: `object`，Modern.js 提供的一系列钩子。
+  - [addMiddleware]: `string | function`，添加中间件的钩子。
+
+## 示例
+
+使用不同的框架，应添加不同框架的中间件；目前支持 express, nest, koa, egg 等框架。
+
+### Express
+
+```ts title=server/index.ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req, res, next) => {
+    req.query.id = 'express';
+    await next();
+  });
+});
+```
+
+### Nest
+
+#### 添加中间件
+
+```ts title=server/index.ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req, res, next) => {
+    req.query.id = 'express';
+    await next();
+  });
+});
+```
+
+#### 添加 Module
+
+```ts title=server/index.ts
+import { hook } from '@modern-js/runtime/server';
+import {
+  Injectable,
+  MiddlewareConsumer,
+  Module,
+  NestMiddleware,
+} from '@nestjs/common';
+
+@Injectable()
+export class LoggerMiddleware implements NestMiddleware {
+  async use(req: any, res: any, next: any) {
+      console.info(`access url: ${req.url}`);
+      next();
+  }
+}
+
+@Module()
+export class AppModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggerMiddleware).forRoutes('*');
+  }
+}
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(AppModule);
+});
+```
+
+### Koa
+
+```ts title=server/index.ts
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    ctx.req.query.id = 'koa';
+    await next();
+  });
+});
+```
+
+### egg
+
+#### 添加中间件
+
+```ts title=server/index.ts
+export default hook(({ addMiddleware }) => {
+  addMiddleware(() => async (ctx, next) => {
+    ctx.req.query.id = 'egg';
+    await next();
+  });
+});
+```
+
+#### 给中间件注入参数
+
+```ts title=server/index.ts
+export default hook(({ addMiddleware }) => {
+  addMiddleware([
+    'eggMiddleware',        // 这里为第三方 node_module 包名
+    {
+      key: 'value',
+    },
+  ])
+});
+```

package/zh/apis/generator/overview.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 0
+---
+
+# 概览
+Modern.js 提供了 `create` 工具用于初始化不同工程方案项目。
+
+## 基本使用
+
+```bash
+npx @modern-js/create [projectDir]
+```
+
+```bash
+Usage: create [projectDir]
+
+创建 @modern-js 应用
+
+Options:
+  -c, --config <config>  创建项目默认配置(JSON 字符串) (default: "{}")
+  --mwa                  一键创建应用工程(使用默认配置) (default: false)
+  --module               一键创建模块工程(使用默认配置) (default: false)
+  --monorepo             一键常见 Monorepo 应用(使用默认配置) (default: false)
+  --dist-tag <distTag>   生成项目时生成器使用特殊的 npm Tag (default: "")
+  --registry <registry>  在创建过程中定制 npm Registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  -h, --help             display help for command
+```
+
+:::info 补充信息
+不需要全局安装 `@modern-js/create`，使用 npx 按需运行即可，可以保证始终运行最新版本的项目生成器。
+:::

package/zh/apis/generator/plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "生成器插件 API",
+  "position": 2
+}

package/zh/apis/generator/plugin/file/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "文件操作 API",
+  "position": 6
+}

package/zh/apis/generator/plugin/file/addFile.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 4
+---
+
+# addFile
+
+添加单个文件。用于添加 `templates` 目录的单个模板文件或者直接使用模板添加到模板文件。
+
+该方法可用于任何文件类型，对于二进制以外的文件类型，添加文件时会进行 Handlebars 渲染。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export interface AddFileParams {
+  type: FileType;
+  file: string;
+  template?: string;
+  templateFile?: string;
+  force?: boolean;
+  data?: Record<string, string>;
+}
+export type ForgedAPI = {
+  addFile: (params: AddFileParams) => Promise<void>;
+  ...
+};
+```
+
+## type
+
+文件类型，具体可查看[文件类型](/docs/apis/generator/plugin/file/introduce#%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B)。
+
+## file
+
+创建的目标文件路径。
+
+## template
+
+文件模板，配置该字段值可直接用于模板渲染文件。优先级低于 templateFile。
+
+## templateFile
+
+模板文件，用于渲染的模板文件路径，其值为 `templates` 的相对路径即可。
+
+## force
+
+是否强制覆盖，当添加的文件已存在时，默认会冲突报错，设置该值为 true 时，可强制覆盖。
+
+## data
+
+Handlebars 渲染数据。

package/zh/apis/generator/plugin/file/addHelper.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 2
+---
+
+# addHelper
+
+针对于文本类型文件，增加 Handlebars 的自定义 Help 函数，具体可查看文档[Custom Helpers](https://handlebarsjs.com/guide/#custom-helpers)。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
+  ...
+};
+```
+
+## name
+
+help 函数名称。
+
+## fn
+
+help 函数实现。

package/zh/apis/generator/plugin/file/addManyFile.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 5
+---
+
+# addManyFile
+
+批量添加文件。用于添加 `templates` 目录的多个文件。
+
+该方法可用于任何文件类型，对于二进制以外的文件类型，添加文件时会进行 Handlebars 渲染。
+
+该方法可在 `onForged` 生命周期的 `api` 参数上获取。
+
+其类型定义为：
+
+```ts
+export interface AddManyFilesParams {
+  type: FileType;
+  destination: string;
+  templateFiles: string[] | (() => string[]);
+  templateBase?: string;
+  fileNameFunc?: (name: string) => string;
+  data?: Record<string, string>; // template data
+}
+export type ForgedAPI = {
+  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
+  ...
+};
+```
+
+## type
+
+文件类型，具体可查看[文件类型](/docs/apis/generator/plugin/file/introduce#%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B)。
+
+## destination
+
+创建的目标文件夹路径。由于是批量添加文件，这里填写需要写入的文件夹路径即可。
+
+## templateFiles
+
+模板文件列表。
+该参数支持函数参数，也支持 [globby 正则](https://www.npmjs.com/package/globby)。
+
+## templateBase
+
+模板基础路径。
+模板路径通常为同一个目录下的模板文件，如果渲染结果需要去除掉模板文件前缀目录，可使用该字段。
+模板渲染文件内容将等于 `templateFiles - templateBase`
+
+## fileNameFunc
+
+重命名文件函数，在该函数中将一次传入渲染的文件名称，可在该函数中进行重命名。
+
+## data
+
+Handlebars 渲染数据。

package/zh/apis/generator/plugin/file/addPartial.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 3
+---
+
+# addPartial
+
+针对于文本类型文件，增加 Handlebars 的自定义 Partial 片段，具体可查看文档[Partials](https://handlebarsjs.com/guide/#partials)。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  addPartial: (name: string, str: Handlebars.Template) => void;
+  ...
+};
+```
+
+## name
+
+partial名称。
+
+## str
+
+partial 模板字符串。

package/zh/apis/generator/plugin/file/introduce.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+---
+
+# 介绍
+
+文件操作 API 可在 onForged 生命周期函数中使用，可对当前项目文件进行增、删、改的操作。
+
+文件操作 API 相关路径填写项目相对路径即可，生成器插件会自动添加当前项目路径前缀。
+
+## 文件类型
+
+生成器插件将文件类型分为一下几类：
+
+- 文本文件：纯文本内容文件，可使用 handlebars 进行模板处理的文件。
+
+- 二进制文件：图片、音频、视频等文件
+
+:::warning
+使用变量的 jsx 或 tsx 文件为二进制文件，其语法与 handlebars 渲染冲突，会造成模板文件创建失败。
+:::
+
+- JSON 文件：JSON 格式的文件，例如 `package.json`、 `tsconfig.json`。
+
+- 文本列表文件：文件由行文本组成的文件，例如 `.gitignore`, `.editorconfig`, `.npmrc`。
+
+生成器插件的文件操作 API 将是针对这四种文件类型进行操作。
+
+其类型定义为：
+```ts
+export enum FileType {
+  Text = 'text',
+  Binary = 'binary',
+  Json = 'json',
+  TextRaw = 'textRaw',
+}
+```

package/zh/apis/generator/plugin/file/rmDir.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 10
+---
+
+# rmDir
+
+删除文件夹。该方法会递归的删除文件夹下的所有文件。
+
+该方法可用于任何文件类型。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  rmDir: (dirName: string) => Promise<void>;
+  ...
+};
+```
+
+## dirName
+
+需删除的文件夹名称或文件夹路径。

package/zh/apis/generator/plugin/file/rmFile.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 9
+---
+
+# rmFile
+
+删除文件。
+
+该方法可用于任何文件类型。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  rmFile: (fileName: string) => Promise<void>;
+  ...
+};
+```
+
+## fileName
+
+需删除的文件名称或文件路径。

package/zh/apis/generator/plugin/file/updateJSONFile.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 6
+---
+
+# updateJSONFile
+
+更新 JSON 文件字段。
+
+该方法适用于 JSON 文件类型，可批量更新 JSON 文件中字段值。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  updateJSONFile: (
+    fileName: string,
+    updateInfo: Record<string, unknown>,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## fileName
+
+JSON 文件的文件名或者文件路径。
+
+## updateInfo
+
+字段更新信息。
+该信息使用 Record 形式表示。
+
+例如需要更新 name 字段：
+
+```ts
+api.updateJSONFile(file, {
+    name: "新名称"
+})
+```
+
+需更新嵌套字段：
+
+```ts
+api.updateJSONFile(file, {
+  "dependencies.name": "新名称"
+})
+```
+
+:::warning
+更新嵌套字段时注意字段名，如果不是全量更新，需将嵌套的 key 也写入字段名中。
+:::

package/zh/apis/generator/plugin/file/updateModernConfig.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 8
+---
+
+# updateModernConfig
+
+更新 `package.json` 中 `modernConfig` 字段。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
+  ...
+};
+```
+
+## updateInfo
+
+字段更新信息。
+
+:::info
+该函数为 updateJSONFile 的封装，将自动更新 `package.json` 的 `modernConfig` 字段 updateInfo 中只需填写相对于 `modernConfig` 的更新信息即可。
+:::

package/zh/apis/generator/plugin/file/updateTextRawFile.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 7
+---
+
+# updateTextRawFile
+
+更新文本列表文件内容。
+
+该方法适用与文本列表文件类型。
+
+该方法可在 onForged 生命周期的 api 参数上获取。
+
+其类型定义为：
+
+```ts
+export type ForgedAPI = {
+updateTextRawFile: (
+    fileName: string,
+    update: (content: string[]) => string[],
+  ) => Promise<void>;
+  ...
+};
+```
+
+## fileName
+
+文本列表文件的文件名或者文件路径。
+
+## update
+
+更新函数。
+
+该函数参数为当前文件内容，内容将以 '\n' 分割，以数组的形式传入函数，函数的返回值也是数组，内部将自动以 '\n' 合并，写入源文件。

package/zh/apis/generator/plugin/git/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "GIT API",
+  "position": 8
+}

package/zh/apis/generator/plugin/git/gitAddAndCommit.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 3
+---
+
+# gitAddAndCommit
+
+提交当前仓库变更。
+
+其类型定义为：
+
+```ts
+export type AfterForgedAPI = {
+  gitAddAndCommit: (commitMessage: string) => Promise<void>;
+  ...
+};
+```
+
+## commitMessage
+
+提交信息。

package/zh/apis/generator/plugin/git/initGitRepo.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 2
+---
+
+# initGitRepo
+
+初始化当前目录为 Git 仓库。
+
+其类型定义为：
+
+```ts
+export type AfterForgedAPI = {
+  initGitRepo: () => Promise<void>;
+  ...
+};
+```