Custom CLI Commands

[pi0]

Related to #10.

Related PR: nuxt/nuxt#4314

Original idea: @galvez

TLDR

A limitation of current module spec is that it doesn't allow adding new commands. We can't add helpers to the module function body because commands are executed before of nuxt instance initialization.

Different ways

1. Universal approach

The @nuxt/cli package exports useful functions to create a good CLI command interface and also benefits of nuxt built-in utilities like config loading and fancy CLI. This pattern allows module package authors to easily create their own bin/ commands with help of a nuxt core module that is also semi-compatible with nuxt projects lower than 2.3.0.

#!/bin/env node -r esm

import { NuxtCommand, run } from '@nuxt/cli'

const cmd = NuxtCommand.from({
    name: 'custom',
    description: 'A custom nuxt command',
    usage: 'nuxt custom',
    async run(cmd) {
      const argv = cmd.getArgv()
      // ...
    }
})

run(cmd)

Positive points:

• Universal compatibility with all nuxt versions
• The is the Node.js standard way of creating new commands
• Commands automatically installed by installing modules
• Module authors have the choice to select the @nuxt/cli version or extend/customize NuxtCommand class.
• Covers local commands

Negative points:

• Listing extra commands with nuxt help is hard but lightweight (Scan path)

Appendix:

For sub-commands support, nuxt CLI can simply map nuxt foo into nuxt-foo and nuxt foo bar into nuxt-foo-bar command and execute it. Preferring convention over platform/PM complexities.

2. js files that @nuxt/cli execute them

The process of adding a command to modules is like creating node_modules/my-module/bin/custom.js that exports a command object like nuxt internal commands. Then by invoking npx nuxt my-command custom nuxt will search for custom command, wraps it into NuxtCommand and runs it.

Positive points:

• Commands automatically installed by installing modules
• Covers local commands

Negative points:

• Only supported for >=2.3.0
• This is the same wrong way of ModuleContainer (Module Improvements #10). The command is implicitly wrapped and command author is not aware who is calling it and what functions exist in nuxtCommand
• Needs extra complexities in the nuxt core (cli package)
• Searching node_modules is not either easy or stable. Different package managers and ways to run are involved (NPX, global cli)
• Custom commands listing hard and costly (Need to scan node_modules)

3. Via module commands export

Module authors can attach module exported commands to the exported function commands object like this:

function myModule(options) {
 // ...
}

myCommand.commands = {
  custom: {
    name: 'custom',
    description: 'A custom nuxt command',
    usage: 'nuxt custom',
    async run(cmd) {
      const argv = cmd.getArgv()
      // ...
    }
  }
}

Positive points:

• Extending modules spec. Allows adding custom commands using nuxt.config.js or writing commands in the same file of module.js
• Listing custom commands are easy (Check for options.modules)

Negative points:

• Only supported for >= 2.3.0
• This is the same wrong way of ModuleContainer (Module Improvements #10). The command is implicitly wrapped and command author is not aware who is calling it and what functions exist in nuxtCommand
• Needs extra complexities in the nuxt core (cli package)
• Modules are nuxt runtime addons by design, not for CLI. (Antipattern)

[galvez]

Thanks for the write-up @pi0 -- It's pretty clear to me that Option 1 is the way to go. Thanks for laying out all pros and cons so thoroughly. Unless anyone wants to voice more concerns, I'm gonna start making the necessary changes in nuxt/nuxt#4314 towards that direction.

[manniL]

👍 for Option 1 ☺️

[atinux]

Let's go for Option 1, awesome write up @pi0, really impressed by it and the time you put into it.

[pi0]

Implemented