插件 API

属性

api.paths

一些关键的路径:

cwd,执行命令的绝对路径
absNodeModulesPath,nodeModule 的绝对路径
absOutputPath,输出 build 产物的绝对路径
absSrcPath,src 目录的绝对路径
absPagesPath,pages目录的绝对路径
absTmpPath,.fes临时文件目录的绝对路径

api.cwd

执行命令的绝对路径

api.pkg

package.json的内容

api.configInstance

config实例

userConfig

用户配置

config

插件配置可被修改,此为最终的配置

env

process.env

args

环境变量

核心方法

describe

注册阶段执行,用于描述插件或插件集的 id、key、配置信息、启用方式等。

用法:describe({ id?: string, key?: string, config?: { default, schema, onChange } }, enableBy?)

例如:

api.describe({
key:'esbuild',
config:{
schema(joi){
returnjoi.object();
},
default:{},
},
enableBy: api.EnableBy.config,
});

注:

config.default 为配置的默认值,用户没有配置时取这个
config.schema 用于声明配置的类型,基于 joi,如果你希望用户进行配置,这个是必须的,否则用户的配置无效
config.onChange 是 dev 阶段配置被修改后的处理机制,默认会重启 dev 进程,也可以修改为 api.ConfigChangeType.regenerateTmpFiles 只重新生成临时文件,还可以通过函数的格式自定义
enableBy 为启用方式,默认是注册启用,可更改为 api.EnableBy.config,还可以用自定义函数的方式决定其启用时机(动态生效)

register

为 api.applyPlugins 注册可供其使用的 hook。

用法:register({ key: string, fn: Function, pluginId?: string, before?: string, stage?: number })

参数:

key:唯一 id
fn:hook 函数,当执行api.applyPlugins时,此函数被执行。
pluginId:插件 id,如果配置了插件 id,则只有此插件未被禁用时,才会执行。

// 可同步
api.register({
key:'foo',
fn(){
return'a';
},
});

// 可异步
api.register({
key:'foo',
asyncfn(){
awaitdelay(100);
return'b';
},
});

注意:

fn 支持同步和异步,异步通过 Promise,返回值为 Promise 即为异步
fn 里的内容需结合 api.appyPlugins 的 type 参数来看,如果是 api.ApplyPluginsType.add,需有返回值,这些返回值最终会被合成一个数组。如果是 api.ApplyPluginsType.modify,需对第一个参数做修改,并返回它,它会作为下个 hook 的参数。如果是 api.ApplyPluginsType.event,无需返回值
stage 和 before 都是用于调整执行顺序的,参考 tapable
stage 默认是 0,设为 -1 或更少会提前执行,设为 1 或更多会后置执行

applyPlugins

取得 register 注册的 hooks 执行后的数据。

用法:applyPlugins({ key: string, type: api.ApplyPluginsType, initialValue?: any, args?: any })

参数:

key:唯一 id
type:hook 的类型。
initialValue:初始值。
args:参数,hook 函数执行时,args 会作为参数传入。

例如:

const foo =await api.applyPlugins({
key:'foo',
type: api.ApplyPluginsType.add,
initialValue: [],
});
console.log(foo);// ['a', 'b']

api.ApplyPluginsType

编译时插件 hook 执行类型,enum 类型,包含三个属性:

compose,用于合并执行多个函数,函数可决定前序函数的执行时机
modify,用于修改值
event,用于执行事件,前面没有依赖关系

registerMethod

往 api 上注册方法。如果有提供 fn,则执行 fn 定义的函数。

用法:registerMethod({ name: string, fn?: Function, exitsError?: boolean })

例如:

api.registerMethod({
name:'writeTmpFile',
fn({path,content}){
assert(api.stage>=api.ServiceStage.pluginReady,'api.writeTmpFile() should not execute in register stage.');
constabsPath=join(api.paths.absTmpPath,path);
api.utils.mkdirp.sync(dirname(absPath));
if (!existsSync(absPath) ||readFileSync(absPath,'utf-8') !==content) {
writeFileSync(absPath,content,'utf-8');
}
},
});

然后在插件中可以使用:

api.writeTmpFile();

registerCommand

注册命令,基于 commander 实现的机制。

用法:registerCommand({ command: string, description: string, fn: Function, options?: Object })

参数:

command
description,描述文字,输入 --help 会打印
fn,命令执行的函数,参数有:
- rawArgv,原始参数
- args,参数
- options,执行命令时附带的的参数配置
- program,commander 对象
options,参数配置,基于 commander 。

例如:

api.registerCommand({
command:'webpack',
description:'inspect webpack configurations',
options: [
{
name:'--rule <ruleName>',
description:'inspect a specific module rule',
},
{
name:'--plugin <pluginName>',
description:'inspect a specific plugin',
},
{
name:'--rules',
description:'list all module rule names',
},
{
name:'--plugins',
description:'list all plugin names',
},
{
name:'--verbose',
description:'show full function definitions in output',
},
 ],
asyncfn({rawArgv,args,options,program}){},
});

当项目引入此插件后,使用:

bash

feswebpack

registerPresets

注册插件集,参数为路径数组。

用法:registerPresets(presets: string[])

例如:

api.registerPresets([{id:'preset_2',key:'preset2',apply:()=>()=>{}}, require.resolve('./preset_3')]);

registerPlugins

注册插件,参数为路径数组。

用法:registerPlugins(plugins: string[])

例如:

api.registerPlugins([{id:'preset_2',key:'preset2',apply:()=>()=>{}}, require.resolve('./preset_3')]);

hasPlugins

判断是否有注册某个插件,插件的 id 规则:

id 默认为包名
内置插件以 @@ 为前缀,比如 @@/registerMethod

用法:hasPlugins(pluginIds: string[])

例如

// 判断是否有注册 @fesjs/plugin-locale
api.hasPlugins(['@fesjs/plugin-locale']);

TIP

如果在注册阶段使用,只能判断在他之前是否有注册某个插件。

hasPresets

判断是否有注册某个插件集。

用法:hasPresets(presetIds: string[])

例如

// 判断是否有注册
api.hasPlugins(['@fesjs/preset-xxx']);

TIP

如果在注册阶段使用,只能判断在他之前是否有注册某个插件集。

skipPlugins

声明哪些插件需要被禁用,参数为插件 id 的数组。

用法:hasPresets(presetIds: string[])

例如:

// 禁用 plugin-model 插件
api.skipPlugins(['@fesjs/plugin-model']);

扩展方法

通过 api.registerMethod() 扩展的方法。

addPluginExports

把插件需要导出的运行时 API 写入@fesjs/fes。

api.addPluginExports(()=> [
{
specifiers: ['access','useAccess'],
source: absoluteFilePath,
},
]);

这样用户使用时:

import{access,useAccess}from'@fesjs/fes';

addCoreExports

提供给其他插件运行时需要的 API。

api.addCoreExports(()=> [
{
specifiers: ['getRoutes'],
source: absCoreFilePath,
},
]);

使用:

import{getHistory,destroyRouter}from'@@/core/coreExports';

addRuntimePlugin

添加运行时插件,返回值格式为表示文件路径的字符串。

例如:

api.addRuntimePlugin(()=>join(__dirname,'./runtime'));

addRuntimePluginKey

添加插件提供的运行时配置的 key,返回值格式为字符串。

例如:

api.addRuntimePluginKey(()=>'some');

则用户可以:

// app.js
const some =function(){
return{};
};

addEntryImportsAhead

在入口文件现有 import 的前面添加 import。

例如:

api.addEntryImportsAhead(()=> [{source:'anypackage'}]);

addEntryImports

在入口文件现有 import 的后面添加 import。

例如:

api.addEntryImport(()=>{
return [
{
 source:'/modulePath/xxx.js',
 specifier:'moduleName',
},
 ];
});

addEntryCodeAhead

在入口文件最前面(import 之后)添加代码。

例如:

api.addEntryCodeAhead(
()=>`${globalCSSFile
.map(file=>`require('${winPath(relative(absTmpPath, file))}');`)
.join('')}`

addEntryCode

在入口文件最后添加代码。

例如:

api.addEntryCode(()=>{
return`console.log('works!')`;
});

addHTMLHeadScripts

在 HTML 头部添加脚本。

例如:

api.addHTMLHeadScripts(()=>{
return [
{
 content:'',
 src:'',
// ...attrs
},
 ];
});

addBeforeMiddlewares

添加在 webpack compiler 中间件之前的中间件,返回值格式为 express 中间件。

例如:

api.addBeforeMiddlewares(()=>{
return(req,res,next)=>{
if (false) {
res.end('end');
}else{
next();
}
};
});

addMiddlewares

添加在 webpack compiler 中间件之后的中间件,返回值格式为 express 中间件。

addTmpGenerateWatcherPaths

添加重新生成临时文件的监听路径。

例如:

api.addTmpGenerateWatcherPaths(()=> ['./app.js']);

chainWebpack

通过 [webpack-chain] 的方式修改 webpack 配置。

例如:

api.chainWebpack((memo)=>{
memo.resolve.alias.set('vue-i18n','vue-i18n/dist/vue-i18n.esm-bundler.js');
});

copyTmpFiles

批量写临时文件。

例如:

api.copyTmpFiles({
 namespace,
path:join(__dirname,'runtime'),
ignore: ['.tpl'],
});

参数:

namespace:复制到临时文件夹下的目标目录
path:需要复制的文件目录
ignore:需要排除的文件

TIP

不能在注册阶段使用,通常放在 api.onGenerateFiles() 里,这样能在需要时重新生成临时文件临时文件的写入做了缓存处理,如果内容一致,不会做写的操作,以减少触发 webpack 的重新编译

getPort

获取端口号,dev 时有效。

getHostname

获取 hostname,dev 时有效。

getServer

获取 devServer,dev 时有效。

getRoutes

获取 api.modifyRoutes 修改过后的路由信息。

getRoutesJSON

获取格式化后的路由信息

modifyRoutes

修改路由。

例如:

// 把BaseLayout插入到路由配置中,作为根路由
api.modifyRoutes((routes)=> [
{
path:'/',
component:winPath(join(api.paths.absTmpPath ||'', absFilePath)),
children: routes,
},
]);

modifyBundleConfigOpts

修改获取 bundleConfig 的函数参数。

例如:

api.modifyBundleConfigOpts((memo)=>{
memo.miniCSSExtractPluginPath=require.resolve('mini-css-extract-plugin');
memo.miniCSSExtractPluginLoaderPath=require.resolve('mini-css-extract-plugin/dist/loader');
returnmemo;
});

modifyBundleConfig

修改 bundle 配置。

api.modifyBundleConfig((bundleConfig)=>{
// do something
returnbundleConfig;
});

modifyBabelOpts

修改 babel 配置项。

例如:

api.modifyBabelOpts((babelOpts)=>{
if (api.config.babelPluginImport) {
api.config.babelPluginImport.forEach((config)=>{
babelOpts.plugins.push(['import',config]);
});
}
returnbabelOpts;
});

modifyBabelPresetOpts

修改 babel 插件的配置。

例如:

api.modifyBabelPresetOpts((opts)=>{
return{
...opts,
};
});

modifyPaths

修改 paths 对象。

modifyDefaultConfig

修改默认配置。例如:

api.modifyDefaultConfig((memo)=>{
return{
...memo,
...defaultOptions,
};
});

modifyConfig

修改最终配置。

例如:

api.modifyConfig((memo)=>{
return{
...memo,
...defaultOptions,
};
});

modifyPublicPathStr

修改 publicPath 字符串。

例如:

api.modifyPublicPathStr(()=>{
returnapi.config.publicPath||'/';
});

onPluginReady

在插件初始化完成触发。在 onStart 之前,此时还没有 config 和 paths,他们尚未解析好。

onStart

在命令注册函数执行前触发。可以使用 config 和 paths。

onExit

dev 退出时触发。

onGenerateFiles

生成临时文件,触发时机在 webpack 编译之前。

restartServer

重启 devServer,dev 时有效。

writeTmpFile

写临时文件。

例如:

api.writeTmpFile({
path: absoluteFilePath,
content: Mustache.render(readFileSync(join(__dirname,'runtime/core.tpl'),'utf-8'),{
REPLACE_ROLES: JSON.stringify(roles),
}),
});

参数:

path:相对于临时文件夹的路径
content:文件内容

TIP

不能在注册阶段使用,通常放在 api.onGenerateFiles() 里,这样能在需要时重新生成临时文件临时文件的写入做了缓存处理,如果内容一致,不会做写的操作,以减少触发 webpack 的重新编译

插件 API ​

属性 ​

api.paths ​

api.cwd ​

api.pkg ​

api.configInstance ​

userConfig ​

config ​

env ​

args ​

核心方法 ​

describe ​

register ​

applyPlugins ​

api.ApplyPluginsType ​

registerMethod ​

registerCommand ​

registerPresets ​

registerPlugins ​

hasPlugins ​

hasPresets ​

skipPlugins ​

扩展方法 ​

addPluginExports ​

addCoreExports ​

addRuntimePlugin ​

addRuntimePluginKey ​

addEntryImportsAhead ​

addEntryImports ​

addEntryCodeAhead ​

addEntryCode ​

addHTMLHeadScripts ​

addBeforeMiddlewares ​

addMiddlewares ​

addTmpGenerateWatcherPaths ​

chainWebpack ​

copyTmpFiles ​

getPort ​

getHostname ​

getServer ​

getRoutes ​

getRoutesJSON ​

modifyRoutes ​

modifyBundleConfigOpts ​

modifyBundleConfig ​

modifyBabelOpts ​

modifyBabelPresetOpts ​

modifyPaths ​

modifyDefaultConfig ​

modifyConfig ​

modifyPublicPathStr ​

onPluginReady ​

onStart ​

onExit ​

onGenerateFiles ​

restartServer ​

writeTmpFile ​