ryor

(R)oll (Y)our (O)wn Task (R)unner for Node.js Projects

No system dependencies

Including ryor as a project development dependency is all that's needed to get started.

No plugins

Unlike task runners or pluggable build tools that require often clunky coordination between unevenly maintained 3rd-party plugins (Gulp, Grunt, Webpack, etc.), ryor offers a convenient means of using tools that already do one thing and do it well as CLIs or Node APIs.

Less clutter

Instead of cluttering of a project's root directory and/or package.json file with configuration files/details, runnables can be neatly self-contained.

Concurrency

Similar to shell, npm or NPS scripts, sequences can be composed that run runnables either serially or concurrently.

Get started:

First, install ryor as a project development dependency: npm install -D ryor

Next, create a subdirectory in your project's root directory for your task runner and runnable ES modules ("tasks" is a good option). A runnable module must export a run value, which can be a string, an array or a function (sync or async). Runnable modules should also export a description value describing what the runnable does ("No description provided" is output in the CLI usage information for the runnable otherwise).

Note: "type": "module" in the project's package.json file is required and version 16 or greater of Node.js is recommended.

Create runnables:

A string run value can be used to call a CLI:

tasks/minify.js

export const description = 'Minifies JavaScript'

export const run = 'minifier --option1 --option2 path/to/file'

A configuration file can be included alongside a runnable ES module by simply creating a directory with an index.js file:

tasks/minify/index.js

export const description = 'Minifies JavaScript'

export const run = 'minifier --config tasks/minify/config.js'

An array run value can be used to call other runnables, CLIs or functions in sequence:

tasks/build.js

export const description = 'Creates production build'

export const run = ['transpile', 'minify', () => (...do something), 'echo "Done."',]

An array run value that begins with the flag -c or --concurrent will run anything following it concurrently:

tasks/develop.js

export const description = 'Runs development watchers and server'

export const run = ['-c', 'transpile --watch', 'lint --watch', 'serve', () => (...start some process for development)]

A run function can be passed arguments which are defined in the args export:

tasks/test.js

export const description = 'Runs tester and optionally collects coverage information'

export const args = {
  coverage: {
    alias: 'c',
    description: 'Collect coverage data',
    type: 'boolean'
  }
}

export async function run({ coverage }) {
  const tester = await import('tester')
  const result = await tester.test(coverage)

  console.log(`Tests complete${coverage ? ' and coverage data collected' : ''}`)
}

A run function can return strings, arrays or functions to run:

tasks/build.js

export const description = 'Creates production build'

export const args = {
  quiet: {
    alias: 'q',
    description: 'No output unless errors are encountered',
    type: 'boolean'
  }
}

export function run({ quiet }) {
  const startTime = Date.now()
  const sequence = [`transpile${quiet ? ' -d' : ''}`, `minify${quiet ? ' -d' : ''}`]

  if (!quiet) sequence.push(`echo "Build took ${Date.now() - startTime}ms."`)

  return sequence
}

Create a runner:

Add an index.js file in your runnables directory that specifies your runnables like this:

tasks/index.js

import ryor from 'ryor'

ryor(['build', 'develop', 'test'])

or, if runnables are separated into subdirectories, like this:

import ryor from 'ryor'

ryor([
  ['main', ['build', 'develop', 'test']],
  ['tools', ['eslint', 'jest', 'tsc']],
  ['utilities', ['log']]
])

Usage information:

To output usage information for all runnables, simply run node [directory name].

Example: node tasks

To output usage information for a specific runnable, run node [directory name] <runnable> -h/--help

Example: node tasks develop -h or node tasks develop --help

Note: When defining arguments for a runnable module, note that help and its h alias are both reserved for all modules.

Usage:

To run a single runnable, use node [directory name] <runnable> [...args]

Example: node tasks build -q

To run more than one runnable in a sequence, use +.

Example: node tasks test + build + publish