@darkobits/nr

nr (short for npm run) is a task runner for JavaScript projects.

It can serve as a replacement for or complement to traditional NPM package scripts.

Contents

• Install
• Philosophy
• Configure
  • command
  • fn
  • script
  • Type-safe Configuration & IntelliSense
• Use
  • Script Name Matching
  • Pre and Post Scripts
  • Discoverability
  • Providing an Explicit Configuration File
• Prior Art

Install

npm install --save-dev @darkobits/nr

This will install the package and create an executable in the local NPM bin path (ie: node_modules/.bin). If your shell is configured to add this location to your $PATH, you can invoke the CLI by simply running nr. Otherwise, you may invoke the CLI by running npx nr.

You may install nr globally, but this is highly discouraged; a project that depends on nr should enumerate it in its devDependencies, guaranteeing version compatibility. And, if your $PATH is configured to include $(npm bin), the developer experience is identical to installing nr globally.

Philosophy

tl;dr Modern task runners don't need plugin systems.

When tools like Grunt and Gulp were conceived, it was common to build JavaScript projects by explicitly streaming source files from one tool to another, each performing some specific modification before writing the resulting set of files to an adjacent directory for distribution.

This pattern almost always relied on Node streams, a notoriously unwieldy API, resulting in the need for a plugin for each tool that a task-runner supported, pushing a lot of complexity from build tools up to the developers that used them.

Modern tools like Babel, Webpack, TypeScript, and Vite allow for robust enough configuration that they can often perform all of these jobs using a single invocation of a (usually well-documented) command-line interface, making plugin systems a superfluous layer of abstraction between the user and the CLI.

Rather than relying on plugins to interface with tooling, nr provides an API for invoking other CLIs, and a means to formalize these invocations in a JavaScript configuration file.

Configure

nr is configured using a JavaScript configuration file, nr.config.js, or a TypeScript configuration file, nr.config.ts. nr will search for this file in the directory from which it was invoked, and then every directory above it until a configuration file is found.

A configuration file is responsible for creating commands, functions, and scripts:

• Commands describe the invocation of a single executable and any arguments provided to it, as well as any configuration related to how the command will run, such as environment variables and how STDIN and STDOUT will be handled.
• Functions are JavaScript functions that may execute arbitrary code. They may be synchronous or asynchronous. Functions can be used to interface with another application's Node API, or to perform any in-process work that does not rely on the invocation of an external CLI.
• Scripts describe a set of instructions composed of commands, functions, and other scripts. These instructions may be run in serial, in parallel, or a combination of both.

A configuration file must default-export a function that will be passed a context object that contains the following keys:

Key	Type	Description
command	function	Create a new command.
fn	function	Create a new function.
script	function	Create a new script.

Example:

nr.config.ts

export default ({ command, fn, script }) => {
  script('build', [
    command('babel', { args: ['src', { outDir: 'dist' }] }),
    command('eslint', { args: 'src' })
  ]);
};

We can then invoke the build script thusly:

nr build

The next sections detail how to create and compose commands, functions, and scripts.

command

Parameter	Type	Description
executable	string	Name of the executable to run.
options?	CommandOptions	Optional arguments and configuration.

Return Type	Description
CommandThunk	Value that may be provided to script to run the command.

This function accepts an executable name and an options object. The object's args property may be used to specify any CommandArguments to pass to the executable. CommandOptions also supports a variety of ways to customize the invocation of a command.

Commands are executed using execa, and CommandOptions supports all valid Execa options.

To reference a command in a script, use either the return value from command or a string in the format cmd:name where name is the value provided in options.name.

Assuming the type Primitive refers to the union of string | number | boolean, CommandArguments may take one the following three forms:

• Primitive to pass a singular positional argument or to list all arguments as a `string``
• Record<string, Primitive> to provide named arguments only
• Array<Primitive | Record<string, Primitive>> to mix positional and named arguments

Each of these forms is documented in the example below.

Argument Casing

The vast majority of modern CLIs use kebab-case for named arguments, while idiomatic JavaScript uses camelCase to define object keys. Therefore, nr will by default convert objects keys from camelCase to kebab-case. However, some CLIs (Such as the TypeScript compiler) use camelCase for named arguments. In such cases, set the preserveArgumentCasing option to true in the commands' options.

Example:

nr.config.ts

import defineConfig from '@darkobits/nr';

export default defineConfig(({ command }) => {
  // Using single primitive arguments. These commands will invoke
  command('echo', { args: 'Hello world!' }); // echo "Hello world!"
  command('sleep', { args: 5 }); // sleep 5

  // Example using a single object of named arguments and preserving argument
  // casing.
  command('tsc', {
    args: { emitDeclarationOnly: true },
    preserveArgumentCasing: true
  }); // tsc --emitDeclarationOnly=true

  // Example using a mix of positional and named arguments.
  command('eslint', {
    args: ['src', { ext: '.ts,.tsx,.js,.jsx' }]
  }); // eslint src --ext=".ts,.tsx,.js,.jsx"

  // Execa's default configuration for stdio is 'pipe'. If a command opens an
  // application that involves interactivity, you'll need to set Execa's stdio
  // option to 'inherit':
  command('vitest', {
    stdio: 'inherit'
  });
});

command.node

This function has the same signature as command. It can be used to execute a Node script using the current version of Node installed on the system. This variant uses execaNode and the options argument supports all execaNode options.

---

fn

Parameter	Type	Description
userFn	Fn	Function to execute.
options?	FnOptions	Function options.

Return Type	Description
FnThunk	Value that may be provided to script to run the function.

This function accepts a function userFn and an optional options object.

To reference a function in a script, use either the return value from fn directly or a string in the format fn:name where name is the value provided in options.name.

Example:

nr.config.ts

import defineConfig from '@darkobits/nr';

export default defineConfig(({ fn, script }) => {
  const helloWorldFn = fn(() => {
    console.log('Hello world!');
  }, {
    name: 'helloWorld'
  });

  const doneFn = fn(() => {
    console.log('Done.');
  }, {
    name: 'done'
  });

  // Just like commands, functions may be referenced in a script by value (and
  // thus defined inline) or using a string with the prefix 'fn:'. The following
  // two examples are therefore equivalent:

  script('myAwesomeScript', [
    helloWorldFn,
    doneFn
  ]);

  script('myAwesomeScript', [
    'fn:helloWorld',
    'fn:done'
  ]);
});

---

script

Parameter	Type	Description
name	string	Name of the script.
instructions	Instruction	Instruction or Array<Instruction>; commands, functions, or other scripts to execute in serial.
options?	ScriptOptions	Optional script configuration.

Return Type	Description
ScriptThunk	Value that may be provided to script to run the script.

This function accepts a name, an instruction set, and an options object, ScriptOptions. It will register the script using the provided name and return a value.

To reference a script in another script, use either the return value from script directly or a string in the format script:name.

The second argument must be an Instruction or array of Instructions. For reference, an Instruction may be one of:

• A reference to a command by name using a string in the format cmd:name or by value using the value returned by command.
• A reference to a function by name using a string in the format fn:name or by value using the value returned by fn.
• A reference to another script by name using a string in the format script:name or by value using the value returned by script.

Parallelization

To indicate that a group of Instructions should be run in parallel, wrap them in an an additional array. However, no more than one level of array nesting is allowed. If you need more complex parallelization, define separate, smaller scripts and compose them.

Example:

nr.config.ts

import defineConfig from '@darkobits/nr';

export default defineConfig(({ command, fn, script }) => {
  command('babel', {
    args: ['src', { outDir: 'dist' }],
    name: 'babel'
  });

  command('eslint', {
    args: ['src'],
    name: 'lint'
  });

  // This script runs a single command, so its second argument need not be
  // wrapped in an array.
  script('test', command('vitest'), {
    description: 'Run unit tests with Vitest.'
  });

  const doneFn = fn(() => console.log('Done!'));

  script('prepare', [
    // 1. Run these two commands in parallel.
    ['cmd:babel', 'cmd:lint']
    // 2. Then, run this script.
    'script:test',
    // 3. Finally, run this function.
    doneFn
  ], {
    description: 'Build and lint in parallel, then run unit tests.'
  });

  script('test.coverage', command('vitest', {
    args: ['run', { coverage: true }]
  }), {
    description: 'Run unit tests and generate a coverage report.'
  });
});

Warning

Scripts will deference their instructions after the entire configuration file has been parsed. This means that if a script calls a command via a string token and something downstream re-defines a new command with the same name, the script will use the latter implementation of the command. This can be a powerful feature, allowing shareable configurations that users can modify in very specific ways. If you want to ensure that a script always uses a specific version of a command, use the pass-by-value method instead of a string token.

---

Type-safe Configuration & IntelliSense

For users who want to ensure their configuration file is type-safe, or who want IntelliSense, you may use a JSDoc annotation in a JavaScript configuration file:

nr.config.ts

/** @type { import('@darkobits/nr').UserConfigurationExport } */
export default ({ command, fn, script }) => {

};

If using a TypeScript configuration file, you can use the satisfies operator:

nr.config.ts

import type { UserConfigurationExport } from '@darkobits/nr';

export default (({ command, fn, script }) => {
  // Define configuration here.
}) satisfies UserConfigurationExport;

Or, nr exports a helper which provides type-safety and IntelliSense without requiring a JSDoc or explicit type annotation.

nr.config.ts

import defineConfig from '@darkobits/nr';

export default defineConfig(({ command, fn, script }) => {
  // Define configuration here.
});

Use

Once you have created an nr.config.(ts|js) file in your project and registered commands, functions, and scripts, you may invoke a registered script using the nr CLI:

nr test.coverage

Or, using a shorthand:

nr t.c

More on using shorthands below.

Script Name Matching

nr supports a matching feature that allows the user to pass a shorthand for the desired script name. Script names may be segmented using a dot, and the matcher will match each segment individually.

For example, if we wanted to execute a script named build.watch, we could use any of the following:

nr build.w
nr bu.wa
nr b.w

Additionally, script name matching is case insensitive, so if we had a script named testScript, the query testscript would successfully match it.

💡 Protip

If a provided shorthand matches more than one script, nr will ask you to disambiguate by providing more characters. What shorthands you will be able to use is therefore dependent on how similarly-named your project's scripts are.

Pre and Post Scripts

Like NPM package scripts, nr supports pre and post scripts. Once a query from the CLI is matched to a specific script, nr will look for a script named pre<matchedScriptName> and post<matchedScriptName>. If found, these scripts will be run before and after the matched script, respectively.

💡 Protip

Because script name matching is case insensitive, a script named build may have pre and post scripts named preBuild and postBuild.

Discoverability

Discoverability and self-documentation are encouraged with nr. While optional, consider leveraging the name, group, and description options where available when defining commands, functions, and scripts. Thoughtfully organizing your scripts and documenting what they do can go a long way in reducing friction for new contributors.

The --commands, --functions, and --scripts flags may be passed to list information about all known entities of that type. If nr detects that a command, function, or script was registered from a third-party package, it will indicate the name of the package that created it.

A new contributor to a project may want an overview of available scripts, and may not be familiar with with the nr CLI. To make this feature easily accessible, consider adding an NPM script to the project's package.json:

{
  "scripts": {
    "help": "nr --scripts"
  }
}

npm run help will now print instructions on how to interact with nr, what scripts are available, and (hopefully) what each one does. Here's an example:

Providing an Explicit Configuration File

To have nr skip searching for a configuration file and use a file at a particular path, pass the --config flag with the path to the configuration file to use.

Prior Art

• NPS - nr was heavily inspired by NPS, originally created by Kent C. Dodds, which itself was inspired by a tweet by Sindre is a Horse.
• npm-run-all - The original package scripts parallelization tool.
• Grunt - The JavaScript task-runner.
• Gulp - The streaming build system.