Skip to main content

@gasket/plugin-command

This plugin enables other plugins to define and inject custom commands into the Gasket CLI. It executes the commands lifecycle during the configure hook, allowing you to extend the functionality of the Gasket CLI with custom commands. The plugin utilizes Commander.js for command management.

Installation​

npm i @gasket/plugin-command

Update your Gasket configuration to include the plugin:

import { makeGasket } from '@gasket/core';
+ import pluginCommand from '@gasket/plugin-command';

export default makeGasket({
  plugins: [
    // other plugins
+    pluginCommand
  ]
});

Lifecycles​

commands​

The commands lifecycle is executed during the configure hook if the gasket CLI command is present in the argv. You can define commands that include arguments, options, and custom parsing logic.

Examples Basic Command​

Define a command with a description and an action:

export default {
  name: 'example-plugin',
  hooks: {
    commands(gasket) {
      return {
        id: 'example-cmd',
        description: 'Example command',
        action: async () => {
          console.log('Hello from example command!');
        }
      };
    }
  }
};

Execute the command:

node ./gasket.js example-cmd
# Output: Hello from example command!

Example Command with Arguments​

Add arguments to your command using the args array:

export default {
  name: 'example-plugin',
  hooks: {
    commands(gasket) {
      return {
        id: 'example-cmd',
        description: 'Example command with arguments',
        args: [
          {
            name: 'message',
            description: 'Message to display',
            required: true
          }
        ],
        action: async (message) => {
          console.log('Message:', message);
        }
      };
    }
  }
};

Run with arguments:

node ./gasket.js example-cmd "Hello, World!"
# Output: Message: Hello, World!

Example Command with Options​

export default {
  name: 'example-plugin',
  hooks: {
    commands(gasket) {
      return {
        id: 'example-cmd',
        description: 'Example command with options',
        options: [
          {
            name: 'message',
            description: 'Message to display',
            required: true,
            short: 'm',
            type: 'string'
          }
        ],
        action: async ({ message }) => {
          console.log('Message:', message);
        }
      };
    }
  }
};

Run with options:

node ./gasket.js example-cmd --message "Hello, World!"
# Output: Message: Hello, World!

Example Command with Parsing​

Use a custom parse function to transform option values:

export default {
  name: 'example-plugin',
  hooks: {
    commands(gasket) {
      return {
        id: 'example-cmd',
        description: 'Example command with parsing',
        options: [
          {
            name: 'list',
            description: 'Comma-separated list of items',
            required: true,
            type: 'string',
            parse: (value) => value.split(',')
          }
        ],
        action: async ({ list }) => {
          console.log('Parsed List:', list);
        }
      };
    }
  }
};

Run with parsing:

node ./gasket.js example-cmd --list "apple,banana,orange"
# Output: Parsed List: [ 'apple', 'banana', 'orange' ]

build​

The build lifecycle allows plugins to hook into the application's build process. This lifecycle is triggered by the build command in the Gasket CLI.

Example​

Define a plugin that hooks into the build lifecycle:

export default {
  name: 'example-plugin',
  hooks: {
    async build(gasket) {
      console.log('Running custom build logic...');
    }
  }
};

Run the build command:

node ./gasket.js build
# Output:
# Running custom build logic...

Example with JSDoc Types​

For type safety, use the CommandsHook type:

export default {
  name: 'example-plugin',
  hooks: {
    /** @type {import('@gasket/plugin-command').CommandsHook} */
    commands(gasket) {
      return {
        id: 'example-cmd',
        description: 'Example command',
        args: [
          {
            name: 'message',
            description: 'Message to display',
            required: true
          }
        ],
        action: async (message) => {
          console.log('Message:', message);
        }
      };
    }
  }
};

Command-based Configuration​

The commands property in the gasket.js file allows you to define configurations that are specific to individual commands. This means that when a particular command is executed, the corresponding configuration values will be applied, ensuring that each command can have its own tailored settings. This helps in managing command-specific behaviors and settings efficiently within your Gasket application.

Example​

Define a command-based configuration in the gasket.js file:

// gasket.js
import { makeGasket } from '@gasket/core';

export default makeGasket({
  message: 'Default message',
  commands: {
    'example-cmd': {
      message: 'Hello, World!' // when the `example-cmd` command is executed, this message will be displayed
    }
  }
});