onForged
onForged 为生成器插件中用于文件操作的生命周期函数。
类型
export type ForgedAPI = {
addFile: (params: AddFileParams) => Promise<void>;
addManyFiles: (params: AddManyFilesParams) => Promise<void>;
updateJSONFile: (fileName: string, updateInfo: Record<string, unknown>) => Promise<void>;
updateTextRawFile: (fileName: string, update: (content: string[]) => string[]) => Promise<void>;
updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
rmFile: (fileName: string) => Promise<void>;
rmDir: (dirName: string) => Promise<void>;
addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
addPartial: (name: string, str: Handlebars.Template) => void;
createElement: (element: ActionElement, params: Record<string, unknown>) => Promise<void>;
enableFunc: (func: ActionFunction, params?: Record<string, unknown> | undefined) => Promise<void>;
};
export type PluginForgedFunc = (
api: ForgedAPI,
inputData: Record<string, unknown>,
) => void | Promise<void>;
export interface IPluginContext {
onForged: (func: PluginForgedFunc) => void;
...
}
onForged 参数为一个回调函数，回调函数参数为 api 和 input，分别用于提供该生命周期函数提供的 API 及当前输入信息。
概念
文件类型
生成器插件将文件类型分为四类：
纯文本内容文件，可使用 Handlebars 或 EJS 进行模板处理的文件。
图片、音频、视频等文件。
JSON 格式的文件。
文件由行文本组成的文件，例如 .gitignore, .editorconfig, .npmrc。
对应四种文件的类型定义为：
export enum FileType {
Text = 'text',
Binary = 'binary',
Json = 'json',
TextRaw = 'textRaw',
}
API
下面将分别介绍 api 参数提供的 API。
addFile
添加单个文件。
参数类型：
export interface AddFileParams {
type: FileType;
file: string;
template?: string;
templateFile?: string;
force?: boolean;
data?: Record<string, string>;
}
type： 文件类型。file：目标文件路径，相对于目标项目目录的相对路径。template：模板内容，该字段值可直接用于模板渲染文件。优先级低于 templateFile。templateFile：模板文件路径，相对于 templates 目录的相对路径即可。force：是否强制覆盖，当目标文件存在时是否强制覆盖，默认为 false。data：模板渲染数据。
INFO
文本类型文件默认使用 Handlebars 进行处理，当模板文件以 .ejs 结尾的话，会使用 EJS 进行模板渲染。
例如添加模板文件 App.tsx.hanlebars 到 src/App.tsx 中:
context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
await api.addFile({
type: FileType.Text,
file: `src/App.tsx`,
templateFile: `App.tsx.handlebars`,
});
})
addManyFiless
批量添加文件，一般用于添加多个文件到同一个目标目录。
参数类型：
export interface AddManyFilesParams {
type: FileType;
destination: string;
templateFiles: string[] | (() => string[]);
templateBase?: string;
fileNameFunc?: (name: string) => string;
data?: Record<string, string>;
}
type： 文件类型。destination：目标文件夹，相对于目标项目目录的相对路径。templateFiles：模板文件列表，支持 globby 正则表达式templateBase：模板文件的公共路径，使用该参数时目标文件会自动删除该路径。fileNameFunc：重命名文件函数，添加文件过程中会依次将文件名传入到该函数，可以根据需要进行重命名。data：模板渲染数据。
例如将模板文件 src-ts 目录下所有文件渲染到 src 目录：
context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
await api.addManyFiles({
type: FileType.Text,
destination: 'src',
templateFiles: ['src-ts/**/*'],
templateBase: 'src-ts',
fileNameFunc: name => name.replace('.handlebars', ''),
});
})
updateJSONFile
更新 JSON 文件字段。
参数类型：
fileName: strings
updateInfo: Record<string, unknown>
fileName：JSON 文件路径，相对于目标项目的路径。updateInfo：更新信息，嵌套字段更新需要平铺，不然会更新整体造成内容丢失。
例如更新 package.json 的 name 字段：
context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
await api.updateJSONFile('package.json', { name: 'new_name' });
})
例如更新 dependencies 的 react-dom 版本:
context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
await api.updateJSONFile('package.json', {
'dependencies.react-dom': '^18',
});
})
更新文本列表文件内容。
参数类型：
fileName: string
update: (content: string[]) => string[]
fileName： 文本列表文件路径，相对于目标项目的路径。update：更新函数，参数为当前文件内容以 \n 进行分割的数组，返回值也为修改完成后的数组，@modern-js/create 会自动以 \n 合并，并写入源文件。
例如 .gitinore 文件中增加 dist 目录：
context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
await api.updateTextRawFile('.gitinore', (content) => [...content, 'dist']);
})
updateModernConfig(不推荐)
Modern.js 配置除了可以在 modern.config.[tj]s 中配置外，还支持 package.json 中配置 modernConfig 配置。该函数用于更新该字段。
参数类型：
updateInfo: Record<string, any>
updateInfo： 更新内容信息。updateModernConfig 是基于 updateJSONFile 的封装，将自动更新到 modernConfig 字段下，updateInfo 中只需填写 modernConfig 下的配置字段即可。
例如开启 ssr：
context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
await api.updateModernConfig({ 'server.ssr': true });
})
rmFile
删除文件。
参数类型：
fileName：删除的文件路径，相对于目标项目的路径。
rmDir
删除文件夹。
参数类型：
dirName：删除的文件夹路径，相对于目标项目的路径。
addHelper
添加 handlebrs 渲染的自定义 Helper。
参数类型：
name: string
fn: Handlebars.HelperDelegate
name：Helper 函数名称。fn：Helper 函数实现。
addPartial
添加 Handlebars 渲染的 Partial。
参数类型：
name: string
str: Handlebars.Template
name：Partial 名称。str：Partial 的模板字符串。
createElement
自动调用 new 命令创建工程元素。
参数类型：
element: ActionElement
params: Record<string, unknown>
element：工程元素类型，新建入口或者新建自定义 Web Server 源码目录。params：对应创建工程元素的其他参数。
enableFunc
自动调用 new 命令开启可选功能。
参数类型：
func: ActionFunction
params?: Record<string, unknown>
func：开启功能名称。params：对应开启功能的其他参数。
