Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

extendCli Plugin Option API #1069

Merged
merged 12 commits into from
Dec 8, 2018
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
"boot": "node scripts/bootstrap.js",
"dev": "yarn workspace docs dev",
"build": "yarn workspace docs build",
"show-help": "yarn workspace docs show-help",
"dev:blog": "yarn workspace blog dev",
"build:blog": "yarn workspace blog build",
"register-vuepress": "lerna exec --scope vuepress -- yarn link",
Expand Down
3 changes: 0 additions & 3 deletions packages/@vuepress/cli/.npmignore

This file was deleted.

18 changes: 0 additions & 18 deletions packages/@vuepress/cli/README.md

This file was deleted.

134 changes: 0 additions & 134 deletions packages/@vuepress/cli/index.js

This file was deleted.

39 changes: 0 additions & 39 deletions packages/@vuepress/cli/package.json

This file was deleted.

3 changes: 2 additions & 1 deletion packages/@vuepress/core/lib/plugin-api/constants.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ const PLUGIN_OPTION_META_MAP = {
ADDITIONAL_PAGES: { name: 'additionalPages', types: [Function, Array] },
GLOBAL_UI_COMPONENTS: { name: 'globalUIComponents', types: [String, Array] },
DEFINE: { name: 'define', types: [Function, Object] },
ALIAS: { name: 'alias', types: [Function, Object] }
ALIAS: { name: 'alias', types: [Function, Object] },
REGISTER_COMMAND: { name: 'registerCommand', types: [Function] }
}

const PLUGIN_OPTION_MAP = {}
Expand Down
4 changes: 3 additions & 1 deletion packages/@vuepress/core/lib/plugin-api/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,8 @@ module.exports = class PluginAPI {
additionalPages,
globalUIComponents,
define,
alias
alias,
registerCommand
}) {
const isInternalPlugin = pluginName.startsWith('@vuepress/internal-')
logger[isInternalPlugin ? 'debug' : 'tip'](pluginLog(pluginName, shortcut))
Expand All @@ -229,6 +230,7 @@ module.exports = class PluginAPI {
.registerOption(PLUGIN_OPTION_MAP.GLOBAL_UI_COMPONENTS.key, globalUIComponents, pluginName)
.registerOption(PLUGIN_OPTION_MAP.DEFINE.key, define, pluginName)
.registerOption(PLUGIN_OPTION_MAP.ALIAS.key, alias, pluginName)
.registerOption(PLUGIN_OPTION_MAP.REGISTER_COMMAND.key, registerCommand, pluginName)
}
}

Expand Down
1 change: 1 addition & 0 deletions packages/@vuepress/core/lib/prepare/AppContext.js
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ module.exports = class AppContext {
*/

constructor (sourceDir, cliOptions = {}, isProd) {
logger.debug('sourceDir', sourceDir)
this.sourceDir = sourceDir
this.cliOptions = cliOptions
this.isProd = isProd
Expand Down
6 changes: 4 additions & 2 deletions packages/@vuepress/core/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,10 +69,12 @@
"webpack-chain": "^4.6.0",
"webpack-merge": "^4.1.2",
"webpack-serve": "^1.0.2",
"webpackbar": "^2.6.1"
"webpackbar": "^2.6.1",
"semver": "^5.5.0",
"cac": "^6.3.3"
},
"engines": {
"node": ">=8"
"node": ">=8.6"
},
"browserslist": [
">1%"
Expand Down
3 changes: 1 addition & 2 deletions packages/docs/docs/miscellaneous/design-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,8 @@ Then the final route of i18n UI is `/i18n/`.

## Others

With the goal of decoupling, we were able to separate VuePress into the following libraries by introducing monorepo:
With the goal of decoupling, we were able to separate VuePress into the following two libraries by introducing monorepo:

- [@vuepress/cli](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/cli): Management of command line;
- [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core):Including the core implementation of `dev`, `build` and `Plugin API`;
- [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default):The default theme you see now.

Expand Down
26 changes: 26 additions & 0 deletions packages/docs/docs/plugin/option-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -434,3 +434,29 @@ Then, VuePress will automatically inject these components behind the layout comp
</div>
</div>
```

## registerCommand

- Type: `function`
- Default: `undefined`

Register a extra command to enhance the CLI of vuepress. The function will be called with a [CAC](https://github.com/cacjs/cac)'s instance as the first argument.

```js
module.exports = {
registerCommand (cli) {
cli
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why call it registerCommand when you can get the entire cli instance 😂

Copy link
Member Author

@ulivz ulivz Dec 7, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How is extendCli?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to extendCli at 1f7bf85

.command('info [targetDir]', '')
.option('--debug', 'display info in debug mode')
.action((dir = '.') => {
console.log('Display info of your website')
})
}
}
```

Now you can use `vuepress info [targetDir]` a in your project!

::: tip
Note that a custom command registered by a plugin requires VuePress to locate your site configuration like `vuepress dev` and `vuepress build`, so when developing a command, be sure to lead the user to pass `targetDir` as an CLI argument.
:::
3 changes: 1 addition & 2 deletions packages/docs/docs/zh/miscellaneous/design-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,8 @@ i18n UI 最终的路由将是 `/i18n/`.

## 其他

本着解耦的目标,引入 monorepo 后,我们也得以将 VuePress 分离成以下几个库
本着解耦的目标,引入 monorepo 后,我们也得以将 VuePress 分离成以下两个库

- [@vuepress/cli](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/cli): 命令行指令的管理;
- [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core):包含 dev、build 的核心实现和 Plugin API;
- [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default):你现在所看到的默认主题。

Expand Down
27 changes: 27 additions & 0 deletions packages/docs/docs/zh/plugin/option-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -436,3 +436,30 @@ VuePress 将会自动将这些组件注入到布局组件的隔壁:
</div>
</div>
```

## registerCommand

- 类型: `function`
- 默认值: `undefined`

注册一个额外的 command 来增强 vuepress 的 CLI。这个函数将会以一个 [CAC](https://github.com/cacjs/cac) 的实例作为第一个参数被调用。

```js
module.exports = {
registerCommand (cli) {
cli
.command('info [targetDir]', '')
.option('--debug', 'display info in debug mode')
.action((dir = '.') => {
console.log('Display info of your website')
})
}
}
```

现在你可以在你项目中使用 `vuepress info [targetDir]` 了!

::: tip
值得注意的是,一个自定义的 command 需要 VuePress 像 `vuepress dev` 或 `vuepress build` 去定位到你的站点配置,所以在开发一个 command 时,请确保引导用户去传入 `targetDir` 作为 CLI 参数的一部分。
:::

3 changes: 2 additions & 1 deletion packages/docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
"description": "docs of VuePress",
"scripts": {
"dev": "vuepress dev docs --temp .temp",
"build": "vuepress build docs --temp .temp"
"build": "vuepress build docs --temp .temp",
"show-help": "vuepress --help"
},
"repository": {
"type": "git",
Expand Down
25 changes: 25 additions & 0 deletions packages/vuepress/lib/checkEnv.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
'use strict'

/**
* Module dependencies.
*/

const { chalk } = require('@vuepress/shared-utils')
const semver = require('semver')

/**
* Expose handleUnknownCommand function.
*/

module.exports = function checkEnv (pkg) {
const requiredVersion = pkg.engines.node

if (!semver.satisfies(process.version, requiredVersion)) {
console.log(chalk.red(
`\n[vuepress] minimum Node version not met:` +
`\nYou are using Node ${process.version}, but VuePress ` +
`requires Node ${requiredVersion}.\nPlease upgrade your Node version.\n`
))
process.exit(1)
}
}
Loading