hins
Version:
[](https://codecov.io/gh/l-zoy/hins) [](https://github.com/l-zoy/hins/blob/master/LICENSE)  • 6.41 kB
Markdown
# hins
[](https://codecov.io/gh/l-zoy/hins) [](https://github.com/l-zoy/hins/blob/master/LICENSE)  [](https://app.circleci.com/pipelines/github/l-zoy/hins)
中间插件程序, 可以快速创建定制化 cli 工具
## 安装
```bash
npm install hins
```
## 用法
暴露一个核心类 `Core`
```js
const { Core } = require('hins')
const core = new Core({
// ...arguments
})
// 需要执行的命令
core.start({ ...arguments })
```
### Core.start()
参数: object
```
{
args?: object
command: string
reloadCommand?: boolean
}
```
- args 接受任何参数, 类型是一个对象, 最后会传入命令插件
- command 启动命令
- reloadCommand 重新运行命令
```js
// 这里先执行了 dev 命令,进入到 dev 插件,
core.start({ command: 'dev' })
// 有的时候需要做命令派发, 在dev插件命令内 做了一些计算,
// 最后得出执行webDev命令. 但是又不需要重新注册插件等前置步奏
core.start({ command: 'webDev', reloadCommand: true })
```
## 接受参数:
### cwd
- 工作区路径
- Type: string
- Default: `process.cwd()`
### babelRegister
- config 和 plugin 的运行时, 使其支持 ts 或 ESNext
- Type: function
- Default: `() => {}`
### possibleConfigName
- 读取配置文件的路径及文件名
- Type: string[]
- Default: `[]`
```js
{
possibleConfigName: ['config.js']
}
```
运行时就会去传入 **cwd** 根目录下找 **config.js** 文件并读取
### plugins
- plugins 配置路径
- Type: string[]
- Default: `[]`
可以是 **绝对路径** 或者 **相对路径**. 相对路径是相对传入的 **cwd** 参数
### watchConfig
- 是否监听配置文件, 如果发现更改则重新运行命令
- Type: object
- Default:
```js
// IChangeTypes:'add' | 'addDir' | 'change' | 'unlink' | 'unlinkDir'
{
changeLog: (type: IChangeTypes, path: string) => void
reloadLog: (type: IChangeTypes, path: string) => void
}
```
## 核心方法:
每个 plugin 都会接受一个 api 实例参数
### describe 注册阶段执行，用于描述插件或插件集的 key、配置信息、启用方式等
参数: object
```
{
key: string,
config: {
default: any,
schema: (joi) => {
return joi.string()
}
}
}
```
```js
api.describe({
key: 'history',
config: {
default: 'browser',
schema(joi) {
return joi.string()
}
}
})
```
```js
// config
export default {
history: 'node'
}
```
注：
- config.default 为配置的默认值，用户没有配置时取这个
- config.schema 用于声明配置的类型，基于 joi，如果你希望用户进行配置，这个是必须的，否则用户的配置无效
### register 为 api.applyHooks 注册可供其使用的 hook
参数: object
```
{
key: string,
fn: Function,
pluginId?: string,
before?: string,
stage?: number
}
```
```js
// 可同步
api.register({
key: 'foo',
fn() {
return 'a';
},
});
// 可异步
api.register({
key: 'foo',
async fn() {
await delay(100);
return 'b';
},
});
然后通过 api.applyHooks 即可拿到 ['a', 'b']，
const foo = await api.applyHooks({
key: 'foo',
type: api.ApplyHookType.add,
initialValue: [],
});
console.log(foo); // ['a', 'b']
```
- fn 支持同步和异步，异步通过 Promise，返回值为 Promise 即为异步
- fn 里的内容需结合 api.applyHooks 的 type 参数来看
- 如果是 api.ApplyHookType.add，需有返回值，这些返回值最终会被合成一个数组
- 如果是 api.ApplyHookType.modify，需对第一个参数做修改，并返回
- 如果是 api.ApplyHookType.event，无需返回值
- stage 和 before 都是用于调整执行顺序的
- stage 默认是 0，设为 -1 或更少会提前执行，设为 1 或更多会后置执行
提供三个便捷调用:
```js
api.applyAddHooks({
key: 'foo',
initialValue: []
})
api.applyModifyHooks({
key: 'modify',
initialValue: 'bar'
})
api.applyEventHooks({
key: 'event'
})
```
### applyHooks 取得 register 注册的 hooks 执行后的数据
参数: object
```
{
key: string,
type:api.ApplyHookType,
initialValue?: any,
args?: any
}
```
相同 key 可能有多个 hook, api.ApplyHookType.add 会返回所有 hook 的数组合值
```js
const foo = await api.applyHooks({
key: 'foo',
type: api.ApplyHookType.add,
initialValue: []
})
console.log(foo) // ['a', 'b']
```
### registerPlugins(plugins: string[]) 注册插件，参数为路径数组
```js
api.registerPlugins([
{ key: 'preset2', apply: (api) => {} },
require.resolve('./preset_3')
])
```
这里内联插件不会进行处理, 直接添加至待执行的插件列表, 因为插件的键名是依照文件路径生成的, 这里的 key 需要填写唯一值
### registerCommand 注册命令
参数: object
```
{
command: string,
alias?: string,
fn: function
}
```
```js
api.registerCommand({
command: 'generate',
alias: 'g',
fn: ({ args }) => {
return `hello ${api.args.projectName}`
}
})
```
alias 为别名，比如 generate 的别名 g fn 的参数为 { args }
### registerMethod
参数: object
```
{
name: string,
fn?: Function,
}
```
往 api 上注册方法。可以是 api.register() 的快捷使用方式，便于调用；也可以不是，如果有提供 fn，则执行 fn 定义的函数。
```js
api.registerMethod({
name: 'foo',
fn() {
return 'foo'
}
})
api.foo()
// 'foo'
```
### configInstance
```js
watchConfig(): void;
// 开启监听config文件
在插件里使用api.configInstance.watchConfig开启监听配置文件, 当修改时会重启
```
## 周期钩子
<!-- 'onPluginReady', 'modifyConfig', 'onStart' -->
### onStart()
在执行命令函数前触发。可以使用 config
```js
api.onStart(() => {
// do something
})
```
### onPluginReady()
在插件初始化完成触发。在 onStart 之前，此时 config 尚未解析好。
```js
api.onPluginReady(() => {
// do something
})
```
### modifyConfig
修改最终配置,参数为最终 config 配置
```js
api.modifyConfig((memo) => {
return {
...memo,
...defaultOptions
}
})
```
修改后的值不会再做 schema 校验