This is a suite of build tools for Node.js projects, really intended to be used for my projects – I make no promises about supporting your use case.

This project was inspired by FT.com Tool Kit, a project we use to build Node.js projects at the Financial Times.

• Requirements
• Usage
  • Setting up
  • Configuration
    • Plugins
      • Extra plugin config
    • Workflows
  • Running workflows
• Available plugins
• Writing plugins
• Contributing
• License

This library requires the following to run:

• Node.js 18+

@rmtc/toolchain is a lightweight task-runner that can be extended with Plugins. Plugins define Steps that can be composed together into Workflows.

These workflows can be run by calling the task runner with one or more workflow names. We'll go into more detail after setting up:

You can automatically create a config file and install the task runner using:

npm create @rmtc/toolchain

If you'd rather do this manually then you can install the task runner with npm and create a minimal config file:

npm install --save-dev @rmtc/toolchain
echo "{ plugins: [], workflows: {} }" > .rmtc.json5

The task runner expects to find a file named .rmtc.json5 in the current working directory. This file is used to define plugins and workflows. The minimal config file is:

{
    plugins: [],
    workflows: {}
}

Plugins are installed as npm modules but still need to be referenced in your config file. We'll use the Biome plugin as an example. First, we install it as a development dependency:

npm install --save-dev @rmtc/plugin-biome

Then we update our config file to include the plugin:

{
    plugins: [
        '@rmtc/plugin-biome'
    ],
    workflows: {}
}

Plugins define Steps and normally some default Workflows. A step is like a single discreet task that you want to run, and a workflow is a list of steps to run in order.

The Biome plugin defines a workflow named verify automatically, so we can already use it with:

npx toolchain verify

When you import a plugin you can also specify some configuration options if the plugin supports any. Sometimes this allows you to import the plugin multiple times to define different workflow steps. Instead of defining the plugin as a string, define it as an array with a config object:

{
    plugins: [
        ['@rmtc/plugin-mocha', {
            coverage: true
        }]
    ],
    workflows: {}
}

In the example above, we're configuring the Mocha plugin plugin to collect code coverage automatically.

Workflows are lists of Steps that your Plugins have defined. Plugins often define default workflows but you can both define your own and override existing workflows in your config file.

Workflows are defined as object properties, the key is the name of the workflow and the value is an array of steps to run:

{
    plugins: [
        '@rmtc/plugin-biome'
    ],
    workflows: {
        doTheLinting: [
            'biome'
        ]
    }
}

Now, instead of using the verify workflow that was defined by the Biome plugin, we can use our doTheLinting workflow:

npx toolchain doTheLinting

You can use this to create your own more complex workflows or remove plugin steps from other workflows that they appear in. E.g. we can disable the default verify workflow from Biome with the following:

{
    plugins: [
        '@rmtc/plugin-biome'
    ],
    workflows: {
        verify: []
    }
}

If you want to know which steps are available to use in your workflows, you can find them with:

npx toolchain --list

Once everything is configured, you can run any of the workflows that you defined yourself or were defined automatically by your plugins. To get a list of available workflows and steps run:

npx toolchain --list

You can run a workflow like this:

npx toolchain <workflow>

e.g.

npx toolchain test

You can also run multiple workflows in sequence, e.g.

npx toolchain verify test

These are the official plugins which are published alongside the core library:

• @rmtc/plugin-biome: validates and formats JavaScript using Biome, with any config found in the project.

• @rmtc/mocha: runs Mocha test suites.

• @rmtc/plugin-npm-scripts: creates package.json scripts for all defined workflows so that you can use npm run <workflow> instead of npx toolchain <workflow>.

• @rmtc/plugin-types-in-jsdoc: validates TypeScript types across all JavaScript files in the project and generates type definition files. It expects a jsconfig.json file to exist in the project.

Plugins are node modules that can either be published to the npm registry or kept on a local file path if it's specific to the project you're working on. All of these are valid plugin definitions:

{
    plugins: [
        '@yourname/my-plugin', // published to npm
        'my-plugin',           // published to npm
        './plugins/my-plugin'  // in a local file
    ],
    workflows: {}
}

For a module to be a valid plugin, it must export a class that extends the @rmtc/plugin Plugin class. This class must be exported as the Plugin export of the module:

const { Plugin } = require('@rmtc/plugin');

exports.Plugin = class Example extends Plugin {
	/**
	 * @type {import('@rmtc/plugin').InitMethod}
	 */
	init() {
		this.defineStep('my-step', () => {
            this.log.info('my plugin works');
        });
		this.defineWorkflow('my-workflow', ['my-step']);
	}
}

More information on extending the plugin class is available in the @rmtc/plugin documentation.

The contributing guide is available here. All contributors must follow this library's code of conduct.

Licensed under the MIT license.
Copyright © 2023, Rowan Manning