feat: more flexible hook system for generators (#2337)

Author: pksunkara

docs/dev-guide/generator-api.md

@@ -54,12 +54,13 @@ Resolve a path for the current project
 
 - **Arguments**
   - `{string} id` - plugin id, can omit the (@vue/|vue-|@scope/vue)-cli-plugin- prefix
+  - `{string} version` - semver version range, optional
 
 - **Returns**
   - `{boolean}`
 
 - **Usage**:
-Check if the project has a plugin with given id
+Check if the project has a plugin with given id. If version range is given, then the plugin version should satisfy it
 
 ## addConfigTransform
 
@@ -177,4 +178,3 @@ Get the entry file taking into account typescript.
 
 - **Usage**:
 Checks if the plugin is being invoked.
-

docs/dev-guide/plugin-dev.md

@@ -241,51 +241,57 @@ Let's consider the case where we have created a `router.js` file via [templating
 api.injectImports(api.entryFile, `import router from './router'`)
 ```
 
-Now, when we have a router imported, we can inject this router to the Vue instance in the main file. We will use `onCreateComplete` hook which is to be called when the files have been written to disk.
+Now, when we have a router imported, we can inject this router to the Vue instance in the main file. We will use `afterInvoke` hook which is to be called when the files have been written to disk.
 
 First, we need to read main file content with Node `fs` module (which provides an API for interacting with the file system) and split this content on lines:
 
 ```js
 // generator/index.js
 
-api.onCreateComplete(() => {
-  const fs = require('fs')
-  const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' })
-  const lines = contentMain.split(/\r?\n/g)
-})
+module.exports.hooks = (api) => {
+  api.afterInvoke(() => {
+    const fs = require('fs')
+    const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' })
+    const lines = contentMain.split(/\r?\n/g)
+  })
+}
 ```
 
 Then we should to find the string containing `render` word (it's usually a part of Vue instance) and add our `router` as a next string:
 
-```js{8-9}
+```js{9-10}
 // generator/index.js
 
-api.onCreateComplete(() => {
-  const fs = require('fs')
-  const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' })
-  const lines = contentMain.split(/\r?\n/g)
+module.exports.hooks = (api) => {
+  api.afterInvoke(() => {
+    const fs = require('fs')
+    const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' })
+    const lines = contentMain.split(/\r?\n/g)
 
-  const renderIndex = lines.findIndex(line => line.match(/render/))
-  lines[renderIndex] += `\n  router,`
-})
+    const renderIndex = lines.findIndex(line => line.match(/render/))
+    lines[renderIndex] += `\n  router,`
+  })
+}
 ```
 
 Finally, you need to write the content back to the main file:
 
-```js{2,11}
+```js{12-13}
 // generator/index.js
 
-api.onCreateComplete(() => {
-  const { EOL } = require('os')
-  const fs = require('fs')
-  const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' })
-  const lines = contentMain.split(/\r?\n/g)
+module.exports.hooks = (api) => {
+  api.afterInvoke(() => {
+    const { EOL } = require('os')
+    const fs = require('fs')
+    const contentMain = fs.readFileSync(api.entryFile, { encoding: 'utf-8' })
+    const lines = contentMain.split(/\r?\n/g)
 
-  const renderIndex = lines.findIndex(line => line.match(/render/))
-   lines[renderIndex] += `${EOL}  router,`
+    const renderIndex = lines.findIndex(line => line.match(/render/))
+    lines[renderIndex] += `${EOL}  router,`
 
-  fs.writeFileSync(api.entryFile, lines.join(EOL), { encoding: 'utf-8' })
-})
+    fs.writeFileSync(api.entryFile, lines.join(EOL), { encoding: 'utf-8' })
+  })
+}
 ```
 
 ## Service Plugin

packages/@vue/cli-plugin-eslint/generator/index.js

@@ -2,6 +2,9 @@ const fs = require('fs')
 const path = require('path')
 
 module.exports = (api, { config, lintOn = [] }, _, invoking) => {
+  api.assertCliVersion('^4.0.0-alpha.4')
+  api.assertCliServiceVersion('^4.0.0-alpha.4')
+
   if (typeof lintOn === 'string') {
     lintOn = lintOn.split(',')
   }
@@ -97,13 +100,13 @@ module.exports = (api, { config, lintOn = [] }, _, invoking) => {
       require('@vue/cli-plugin-unit-jest/generator').applyESLint(api)
     }
   }
+}
 
+module.exports.hooks = (api) => {
   // lint & fix after create to ensure files adhere to chosen config
-  if (config && config !== 'base') {
-    api.onCreateComplete(() => {
-      require('../lint')({ silent: true }, api)
-    })
-  }
+  api.afterAnyInvoke(() => {
+    require('../lint')({ silent: true }, api)
+  })
 }
 
 const applyTS = module.exports.applyTS = api => {

packages/@vue/cli/__tests__/Generator.spec.js

@@ -448,7 +448,24 @@ test('api: onCreateComplete', () => {
         }
       }
     ],
-    completeCbs: cbs
+    afterInvokeCbs: cbs
+  })
+  expect(cbs).toContain(fn)
+})
+
+test('api: afterInvoke', () => {
+  const fn = () => {}
+  const cbs = []
+  new Generator('/', {
+    plugins: [
+      {
+        id: 'test',
+        apply: api => {
+          api.afterInvoke(fn)
+        }
+      }
+    ],
+    afterInvokeCbs: cbs
   })
   expect(cbs).toContain(fn)
 })

packages/@vue/cli/lib/Creator.js

@@ -54,7 +54,8 @@ module.exports = class Creator extends EventEmitter {
     this.outroPrompts = this.resolveOutroPrompts()
     this.injectedPrompts = []
     this.promptCompleteCbs = []
-    this.createCompleteCbs = []
+    this.afterInvokeCbs = []
+    this.afterAnyInvokeCbs = []
 
     this.run = this.run.bind(this)
 
@@ -64,7 +65,7 @@ module.exports = class Creator extends EventEmitter {
 
   async create (cliOptions = {}, preset = null) {
     const isTestOrDebug = process.env.VUE_CLI_TEST || process.env.VUE_CLI_DEBUG
-    const { run, name, context, createCompleteCbs } = this
+    const { run, name, context, afterInvokeCbs, afterAnyInvokeCbs } = this
 
     if (!preset) {
       if (cliOptions.preset) {
@@ -187,7 +188,8 @@ module.exports = class Creator extends EventEmitter {
     const generator = new Generator(context, {
       pkg,
       plugins,
-      completeCbs: createCompleteCbs
+      afterInvokeCbs,
+      afterAnyInvokeCbs
     })
     await generator.generate({
       extractConfigFiles: preset.useConfigFiles
@@ -204,7 +206,10 @@ module.exports = class Creator extends EventEmitter {
     // run complete cbs if any (injected by generators)
     logWithSpinner('⚓', `Running completion hooks...`)
     this.emit('creation', { event: 'completion-hooks' })
-    for (const cb of createCompleteCbs) {
+    for (const cb of afterInvokeCbs) {
+      await cb()
+    }
+    for (const cb of afterAnyInvokeCbs) {
       await cb()
     }
 

packages/@vue/cli/lib/Generator.js

@@ -1,12 +1,14 @@
 const ejs = require('ejs')
 const debug = require('debug')
+const semver = require('semver')
 const GeneratorAPI = require('./GeneratorAPI')
+const PackageManager = require('./util/ProjectPackageManager')
 const sortObject = require('./util/sortObject')
 const writeFileTree = require('./util/writeFileTree')
 const inferRootOptions = require('./util/inferRootOptions')
 const normalizeFilePaths = require('./util/normalizeFilePaths')
 const runCodemod = require('./util/runCodemod')
-const { toShortPluginId, matchesPluginId } = require('@vue/cli-shared-utils')
+const { toShortPluginId, matchesPluginId, loadModule, isPlugin } = require('@vue/cli-shared-utils')
 const ConfigTransform = require('./ConfigTransform')
 
 const logger = require('@vue/cli-shared-utils/lib/logger')
@@ -69,17 +71,20 @@ module.exports = class Generator {
   constructor (context, {
     pkg = {},
     plugins = [],
-    completeCbs = [],
+    afterInvokeCbs = [],
+    afterAnyInvokeCbs = [],
     files = {},
     invoking = false
   } = {}) {
     this.context = context
     this.plugins = plugins
     this.originalPkg = pkg
     this.pkg = Object.assign({}, pkg)
+    this.pm = new PackageManager({ context })
     this.imports = {}
     this.rootOptions = {}
-    this.completeCbs = completeCbs
+    this.afterInvokeCbs = []
+    this.afterAnyInvokeCbs = afterAnyInvokeCbs
     this.configTransforms = {}
     this.defaultConfigTransforms = defaultConfigTransforms
     this.reservedConfigTransforms = reservedConfigTransforms
@@ -93,15 +98,49 @@ module.exports = class Generator {
     // exit messages
     this.exitLogs = []
 
+    const pluginIds = plugins.map(p => p.id)
+
+    // load all the other plugins
+    this.allPlugins = Object.keys(this.pkg.dependencies || {})
+      .concat(Object.keys(this.pkg.devDependencies || {}))
+      .filter(isPlugin)
+
     const cliService = plugins.find(p => p.id === '@vue/cli-service')
     const rootOptions = cliService
       ? cliService.options
       : inferRootOptions(pkg)
+
+    // apply hooks from all plugins
+    this.allPlugins.forEach(id => {
+      const api = new GeneratorAPI(id, this, {}, rootOptions)
+      const pluginGenerator = loadModule(`${id}/generator`, context)
+
+      if (pluginGenerator && pluginGenerator.hooks) {
+        pluginGenerator.hooks(api, {}, rootOptions, pluginIds)
+      }
+    })
+
+    // We are doing save/load to make the hook order deterministic
+    // save "any" hooks
+    const afterAnyInvokeCbsFromPlugins = this.afterAnyInvokeCbs
+
+    // reset hooks
+    this.afterInvokeCbs = afterInvokeCbs
+    this.afterAnyInvokeCbs = []
+    this.postProcessFilesCbs = []
+
     // apply generators from plugins
     plugins.forEach(({ id, apply, options }) => {
       const api = new GeneratorAPI(id, this, options, rootOptions)
       apply(api, options, rootOptions, invoking)
+
+      if (apply.hooks) {
+        apply.hooks(api, options, rootOptions, pluginIds)
+      }
     })
+
+    // load "any" hooks
+    this.afterAnyInvokeCbs = afterAnyInvokeCbsFromPlugins
   }
 
   async generate ({
@@ -242,12 +281,22 @@ module.exports = class Generator {
     debug('vue:cli-files')(this.files)
   }
 
-  hasPlugin (_id) {
+  hasPlugin (_id, _version) {
     return [
       ...this.plugins.map(p => p.id),
-      ...Object.keys(this.pkg.devDependencies || {}),
-      ...Object.keys(this.pkg.dependencies || {})
-    ].some(id => matchesPluginId(_id, id))
+      ...this.allPlugins
+    ].some(id => {
+      if (!matchesPluginId(_id, id)) {
+        return false
+      }
+
+      if (!_version) {
+        return true
+      }
+
+      const version = this.pm.getInstalledVersion(id)
+      return semver.satisfies(version, _version)
+    })
   }
 
   printExitLogs () {

packages/@vue/cli/lib/GeneratorAPI.js

@@ -133,10 +133,11 @@ class GeneratorAPI {
    * Check if the project has a given plugin.
    *
    * @param {string} id - Plugin id, can omit the (@vue/|vue-|@scope/vue)-cli-plugin- prefix
+   * @param {string} version - Plugin version. Defaults to ''
    * @return {boolean}
    */
-  hasPlugin (id) {
-    return this.generator.hasPlugin(id)
+  hasPlugin (id, version) {
+    return this.generator.hasPlugin(id, version)
   }
 
   /**
@@ -280,7 +281,21 @@ class GeneratorAPI {
    * @param {function} cb
    */
   onCreateComplete (cb) {
-    this.generator.completeCbs.push(cb)
+    this.afterInvoke(cb)
+  }
+
+  afterInvoke (cb) {
+    this.generator.afterInvokeCbs.push(cb)
+  }
+
+  /**
+   * Push a callback to be called when the files have been written to disk
+   * from non invoked plugins
+   *
+   * @param {function} cb
+   */
+  afterAnyInvoke (cb) {
+    this.generator.afterAnyInvokeCbs.push(cb)
   }
 
   /**

packages/@vue/cli/lib/add.js

@@ -5,8 +5,7 @@ const PackageManager = require('./util/ProjectPackageManager')
 const {
   log,
   error,
-  resolvePluginId,
-  resolveModule
+  resolvePluginId
 } = require('@vue/cli-shared-utils')
 const confirmIfGitDirty = require('./util/confirmIfGitDirty')
 
@@ -27,12 +26,7 @@ async function add (pluginName, options = {}, context = process.cwd()) {
   log(`${chalk.green('✔')}  Successfully installed plugin: ${chalk.cyan(packageName)}`)
   log()
 
-  const generatorPath = resolveModule(`${packageName}/generator`, context)
-  if (generatorPath) {
-    invoke(pluginName, options, context)
-  } else {
-    log(`Plugin ${packageName} does not have a generator to invoke`)
-  }
+  invoke(pluginName, options, context)
 }
 
 module.exports = (...args) => {