egg-artisan

A cli plugin for egg, named artisan, based on common-bin.

Install

$ npm i egg-artisan --save

Mount

// {app_root}/config/plugin.js
exports.artisan = {
  enable: true,
  package: 'egg-artisan',
};

Features

egg-artisan provides a cli running mode for egg. In the root directory, you can do something by executing commands like npm run artisan xxx, such as operating file, manipulating database scripts, updating cache scripts, etc.

egg-artisan based on common-bin(based on yargs), to provide more convenient usage, as detailed below.

Usage

egg-artisan requires cli file to be stored in app/artisan, as shown below, test.js, clone.js.

    egg-project
    ├── app
    │   ├── artisan
    │   |   ├── test.js
    │   |   └── clone.js
    │   ├── controller
    |   ├── router.js
    |   | ...
    ├── package.json
    ├── config
    ├── test
    ├── app.js (可选)
    ├── ...

How to write command

Let's take test.js as an example, for the file operation.

As you can see, the usage of the command is the same as that of common-bin, because egg-artisan extends common-bin. In addition, egg-artisan injected ths.ctx into the run method, so you can get anonymous context with ths.ctx.

You can see common-bin, http://yargs.js.org/docs for more detail.

// {app_root}/app/artisan/test.js

'use strict';

const Command = require('egg-artisan');

class TestCommand extends Command {
  constructor(rawArgv) {
    super(rawArgv);
    this.yargs.usage('test command');

    this.yargs.options({
      a: {
        type: 'string',
        description: 'test argv: a description',
      },
    });
  }

  async run({ argv }) {
    const aa = argv.a || '';
    const bb = argv.b || '';
    const cc = argv._.join(',');
    await this.ctx.service.file.write(`argv: ${aa}${bb}${cc}`);
    const con = await this.ctx.service.file.read();
    console.log('argv', argv);
    return con;
  }

  get description() {
    return 'test description';
  }
}

module.exports = TestCommand;

Add egg-artisan to package.json scripts:

{
  "scripts": {
    "artisan": "egg-artisan"
  }
}

Run the test command

• Show help, the following image has 2 custom commands: test.js, clone.js.

$ npm run artisan
// The following is the same
// npm run artisan -- -h
// npm run artisan -- help

Why use -- ? you can see http://www.ruanyifeng.com/blog/2016/10/npm_scripts.html.

![](./img/1.png)

• Show test.js command help

$ npm run artisan -- test -h
// The following is the same
// npm run artisan -- test help

• Run test.js command

$ npm run artisan -- test -x=1 --type=2 a b

// The following is the same
// npm run artisan -- test -x=1 --type 2 a b
// npm run artisan -- test -x 1 --type 2 a b

Call the artisan command inside the project

egg-artisan provides app.runArtisan(artisanCommand, [argvs]) for running some commands inside the project. app.runArtisan(artisanName, [argvs]) accepts two parameters:

• artisanCommand: Relative path or absolute path in the app/artisan directory, such as test, {app_root}/app/artisan/test; You can also append parameters, such as test -x=1 --type=2, {app_root}/app/artisan/test -x=1 --type=2.
• argvs: command argvs, will be parsed and appended to artisanCommand. support object, array, such as [ 'a', 'b' ], { '--a': 1, '--b': 2 }, { a: true, '--b': 2 }.

Example:

// {app_root}/app/controller/home.js 
'use strict';

const BaseController = require('./base');

class HomeController extends BaseController {
  async index() {
    await this.app.runArtisan('test', { '-a': 1 })
}

module.exports = HomeController;

more usage, reference npm run artisan:

npm run artisan -- test
app.runArtisan('test')

npm run artisan -- test -a=1
app.runArtisan('test -a=1')
app.runArtisan('test', { '-a': 1 })

npm run artisan -- test a b
app.runArtisan('test a b')
app.runArtisan('test', [ 'a', 'b' ])

npm run artisan -- test -a=1 --bb=2
app.runArtisan('test -a=1 --bb=2')
app.runArtisan('test', { '-a': 1, '--bb': 2 })

npm run artisan -- test -a=1 --bb=2 cc
app.runArtisan('test -a=1 --bb=2 cc')
app.runArtisan('test -a=1', { '--bb': 2, cc: true })
app.runArtisan('test', { '-a': 1, '--bb': 2, cc: true })

advanced usage

• Combined egg-schedule

  // {app_root}/app/schedule/xxx.js
  const Subscription = require('egg').Subscription;
  class ClusterTask extends Subscription {
    static get schedule() {
      return {
        type: 'custom',
      };
    }
    async subscribe(data) {
      await this.ctx.app.runArtisan('test', { '-a': 1 });
    }
  }

Questions & Suggestions

Please open an issue here.

License

MIT