插件 API

优质

小牛编辑

128浏览

2023-12-01

属性

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) {
            return joi.object();
        },
        default: {}
    },
    enableBy: api.EnableBy.config,
});

注：

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

applyPlugins

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

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

参数：

key
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，用于执行事件，前面没有依赖关系

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'
    }],
    async fn({ rawArgv, args, options, program}) {
    }
})

当项目引入此插件后，使用：

fes webpack

registerMethod

往 api 上注册方法。可以是 api.register() 的快捷使用方式，便于调用；也可以不是，如果有提供 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.'
        );
        const absPath = join(api.paths.absTmpPath, path);
        api.utils.mkdirp.sync(dirname(absPath));
        if (!existsSync(absPath) || readFileSync(absPath, 'utf-8') !== content) {
            writeFileSync(absPath, content, 'utf-8');
        }
    }
});

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']);

提示

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

hasPresets

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

用法：hasPresets(presetIds: string[])

例如

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

提示

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

扩展方法

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

onStart

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

onExit

dev 退出时触发。

onGenerateFiles

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

addPluginExports

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

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

这样用户使用时：

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

addRuntimePlugin

添加运行时插件，返回值格式为表示文件路径的字符串。Fes.js 会把

例如：

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

addRuntimePluginKey

添加运行时插件的 key，返回值格式为字符串。

例如：

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

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!')`
})

addBeforeMiddlewares

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

例如：

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

addMiddlewares

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

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',
    );
    return memo;
});

modifyBundleConfig

修改 bundle 配置。

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

modifyBabelOpts

修改 babel 配置项。

例如：

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

modifyBabelPresetOpts

修改 babel 插件的配置。

例如：

api.modifyBabelPresetOpts(opts => {
    return {
      ...opts,
      import: (opts.import || []).concat([
        { libraryName: 'ant-design-vue', libraryDirectory: 'es', style: true },
      ]),
    };
});

modifyPaths

修改 paths 对象。

modifyConfig

修改最终配置。

例如：

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

chainWebpack

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

例如：

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

addTmpGenerateWatcherPaths

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

例如：

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

writeTmpFile

写临时文件。

例如：

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

参数：

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

提示

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

copyTmpFiles

批量写临时文件。

例如：

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

参数：

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

提示

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