Skip to main content

通过插件定制工程能力

插件工程能力通过 src/index.ts 定义，结构如下

module.exports = ({ context, onGetWebpackConfig, log, onHook, ...rest }, options) => {
// 第一项参数为插件 API 提供的能力
// options：插件自定义参数
};

该方法会接收两个参数，第一个参数是插件提供的 API 接口，推荐按照解构方式使用，第二个参数 options 是插件自定义的参数，由插件开发者决定提供哪些选项给用户配置。

插件 API#

通过插件提供的 API，可以方便拓展和自定义能力。

context#

包含运行时的各种环境信息：

  • command 当前运行命令，start/build/test
  • commandArgs script 命令执行时接受到的参数
  • rootDir 项目根目录
  • userConfig 用户在 build.json 中配置的内容
  • pkg 项目 package.json 中的内容

onGetWebpackConfig#

通过 onGetWebpackConfig 获取 webpack-chain 形式的配置，并对配置进行自定义修改：

module.exports = ({onGetWebpackConfig, registerTask}) => {
registerTask('default', webpackConfig);
onGetWebpackConfig((config) => {
config.entry('xxx');
});
}

onGetJestConfig#

通过 onGetJestConfig 获取 jest 配置，可对配置进行自定义修改：

module.exports = ({onGetJestConfig}) => {
onGetJestConfig((jestConfig) => {
const modifiedJestConfig = modify(jestConfig);
return modifiedJestConfig;
});
};

onHook#

通过 onHook 监听命令运行时事件，onHook 注册的函数执行完成后才会执行后续操作，可以用于在命令运行中途插入插件想做的操作：

module.exports = ({ onHook }) => {
onHook('before.build.load', () => {
// do something before dev
});
onHook('after.build.compile', (stats) => {
// do something after build
});
}

目前支持的命令执行生命周期如下：

start 命令#

生命周期参数调用时机
before.start.load{
  args: CommandArgs, // 启动参数
webpackConfig: ConfigInfo[]
}		配置转化之前
before.start.run{
  args: CommandArgs, // 启动参数
config: WebpackConfig[]
}		构建执行之前
after.start.compile{
  url: string // serverUrl,
isFirstCompile: boolean,
  stats: WebpackAssets // Vite 模式下不存在 stats
}		编译结束，每次重新编译都会执行
before.start.devServer{
  url: string // serverUrl,
 devServer:  WebpackDevServer		viteServer
}
after.start.devServer{
  url: string // serverUrl,
  devServer: WebpackDevServer ｜ viteServer,
  err: Error
}		dev server 启动后，仅支持 Webpack 构建模式

build 命令#

生命周期参数调用时机
before.build.load{
  args: CommandArgs, // 启动参数
webpackConfig: ConfigInfo[]
}		配置转化之前
before.build.run{
  args: CommandArgs, // 启动参数
config: WebpackConfig[]
}		构建执行之前
after.build.compile{
  err: Error,
  stats: WebpackAssets // Vite 模式下不存在 stats
}		构建结束

test 命令#

生命周期参数调用时机
before.test.load{
  args: array // 启动参数
}		获取 jest 配置之前
before.test.run-jest 执行之前
after.test{
  result // jest执行结果
}		测试命令执行结束

log#

统一的 log 工具，底层使用 npmlog ，便于生成统一格式的 log。

log.info('start');
log.verbose('debug');
log.error('exit');

registerUserConfig#

为用户配置文件 build.json 中添加自定义字段。

module.exports = ({registerUserConfig}) => {
registerUserConfig({
name: 'custom-key',
validation: 'boolean' // 可选，支持类型有 string, number, array, object, boolean
});
};

registerClioption#

为命令行启动添加自定义参数。

module.exports = ({registerClioption}) => {
registerCliOption({
name: 'custom-option', // 参数名
commands: ['start'], // 命令
configWebpack: (arg) => {} // 可选，arg 为命令行参数对应值
});
};

registerMethod#

注册自定义方法。通过 applyMethod 调用。

module.exports = ({registerMethod}) => {
registerMethod(name, func); // name, func 分别为方法名和方法
};

modifyUserConfig#

修改用户配置文件。

module.exports = ({modifyUserConfig}) => {
modifyUserConfig(key, value); // key, value 分别为用户配置文件键值对
};

registerTask#

添加 Webpack 配置，配置为 webpack-chain 形式。

module.exports = ({registerTask}) => {
registerTask(name, config); // name: Task名, config: webpack-chain 形式的配置
};

getAllTask#

获取所有 Webpack 配置名称。

module.exports = ({getAllTask}) => {
const alltasks = getAlltask();
};

getAllPlugin#

获取所有插件。

module.exports = ({getAllPlugin}) => {
// 获取所有插件数组
// 类型：() => [{pluginPath, options, name}]
const plugins = getAllPlugin(); ，[]
}

扩展 API#

除了以上由 build-scripts 内置支持的 API，我们还通过 icejs 对插件 API 做了扩展，扩展的 API 需要通过以下方式调用：

module.exports = ({ applyMethod }) => {
// 第一个参数对应 API 名称，第二个参数对应 API 参数
applyMethod('addIceExport', { source: `./config`, exportName });
}

addPluginTemplate#

为运行时目录中的模版生成提供统一的渲染服务（目录）：

// 默认渲染目录由插件名称决定
applyMethod('addPluginTemplate', path.join(__dirname, '../template'));
// 指定模版渲染目录
const renderData = {}; // 可选，ejs 额外渲染参数
applyMethod('addPluginTemplate', {
template: path.join(__dirname, '../src/types'),
targetDir: 'router/types',
}, renderData);

addRenderFile#

向运行时目录添加提供文件的渲染服务（文件）：

const sourceFile = '../template/index.tsx.ejs');
const targetFile = path.join(runtimeDir, 'source/index.tsx');
const renderData = {}; // 可选，ejs 额外渲染参数
applyMethod('addRenderFile', path.join(__dirname, sourceFile, targetFile, renderData);

addExport#

向 ice 里注册模块，实现 import { foo } from 'ice'; 的能力：

// API 参数
// source: 指定导出模块引入的文件目录
// exportName: 从 ice 中导出的模块名称。
// specifier: 从 source 中默认导出方式，可选，默认值为 default export，如果为 named export 需要额外设置
//
// 实现 import { request } from 'ice'; request 由插件的 `./request/request` 文件实现
applyMethod('addExport', { source: './request/request', exportName: 'request' })

addAppConfigTypes#

向 appConfig 添加类型

// 第一项参数对应 API 名称，第二项参数对应 API 参数。
//
// API 参数：
// source: 类型声明文件。./foo/types，对应 ICE_TEMP_DIR/foo/types。 ICE_TEMP_DIR，可通过 getValue('TEMP_PATH') 获得。注意：需先将对应类型文件移至 ICE_TEMP_DIR。
// specifier: 导出类型标识符，可选，默认值为 '*'。
// exportName: 添加至 appConfig 类型 IAppConfig 上的导出名。
//
// 结果为：
// // ICE_TEMP_DIR/types.ts
// import { Foo } from './foo/types';
// export interface IAppConfig {
// foo?: Foo
// }
applyMethod('addAppConfigTypes', { source: `./foo/types`, specifier: '{ Foo }', exportName: `foo?: Foo` });

getPages#

获取 src/pages 下的一级页面列表：

// ['Home', 'About']
const pages = this.applyMethod('getPages', this.rootDir);

addDisableRuntimePlugin#

禁用插件的运行时能力

// 禁用内置的 request 的运行时能力
applyMethod('addDisableRuntimePlugin', 'build-plugin-ice-request');

watchFileChange#

监听 src 下的文件变化：

applyMethod('watchFileChange', 'src/config.*', async (event: string) => {
if (event === 'unlink' || event === 'add') {
// do something
}
});

插件参数#

用户可以在 build.json 中指定插件参数：

{
"plugins": [
["build-plugin-foo", {
"type": "bar"
}]
]
}

那么在 build-plugin-foo 里就可以获取到这个参数：

module.exports = ({ context, log }, options) => {
const { type } = options;
log.info(type); // => bar
}

插件通信#

插件间需要进行通信的场景诉求：

  1. 不同插件之间需要知道彼此的存在来确定是否执行相应的逻辑
  2. 多个插件共有的配置信息可以抽出来，在某个插件中进行配置

使用 setValue 和 getValue 两个API来实现，分别用于数据的存取。

setValue#

类型：(key: string | number, value: any) => void，示例：

// build-plugin-test
module.exports = ({ setValue }) => {
setValue('key', 123);
}

getValue#

类型：(key: string | number) => any，示例：

module.exports = ({getValue}) => {
const value = getValue('key'); // 123
}

同时在 icejs 中也内置了几个变量：

const projectType = getValue('PROJECT_TYPE'); // ts|js
const iceDirPath = getValue('TEMP_PATH'); // 对应 .ice 的路径

类型#

接口类型通过以下方法引入：

import { IPlugin } from 'build-scripts';
Edit this page