command

A command in nr encapsulates a reference to an external executable (CLI, script, etc), the arguments to pass to it, and configuration related to how to handle its output. Commands may then be invoked by scripts.

To create a command, use the function at the command property of the context object passed to your configuration function:

nr.config.js

export default ({ command }) => {
    
};

command

This function accepts the following parameters:

name: string

Human friendly name for the command. This will be used for error-reporting and can be used to reference the command in scripts.

args: CommandArguments

Array containing the executable/file to run and any arguments to pass to it. This array may take one of four forms, described below.

• [executable] of type [string]

• [executable, positionals] of type [string, Array<string>]

• [executable, flags] of type [string, Record<string, any>]

• [executable, positionals, flags] of type [string, Array<string>, Record<string, any>]

Example:

nr.config.js

export default ({ command }) => {
  // [executable] form:
  command('unit-test', ['jest']);
  
  // [executable, positionals] form:
  command('lint', ['eslint', ['src']]);
  
  // [executable, flags] form:
  command('type-check', ['tsc', { noEmit: true }], {
    // See "Argument Casing" below.
    preserveArgumentCasing: true
  });
  
  // [executable, positionals, flags] form:
  command('compile', ['babel', ['src'], { outDir: 'dist' }]);
};

This approach may seem verbose at first, but compared to a single, raw string it separates the parts of a command invocation into discreet values that enable re-use:

nr.config.js

export default ({ command }) => {
  // This list may be used to configure other commands as well.
  const extensions = ['.ts', '.tsx', '.js', '.jsx'];

  const commonBabelFlags = {
    extensions: extensions.join(','),
    outDir: 'dist',
    copyFiles: true,
    sourceMaps: true
    deleteDirOnStart: true
  };
  
  command('compile', ['babel', ['src'], commonBabelFlags]);
  
  command('compile-watch', ['babel', ['src'], {
    ...commonBabelFlags,
    watch: true
  }]);
};

Commands are not executed in a shell environment where you can use constructs like &&, ||, or$?. Rather, a command should be shell-agnostic and point to a single executable file that will be invoked without an interpreter like cmd.exe or /bin/bash.

options?: CommandOptions

Commands may be further configured by passing an optional options object as the third parameter to command. Its properties are detailed below.

prefix?: (chalk: Chalk) => string

Function that will be passed a chalk instance and should return a string. This string will be used to prefix each line of output from the command.

This feature can be useful in cases where scripts run multiple commands in parallel or when a CLIs output may not make it obvious what program the output is coming from.

Example:

In this example, let's add a prefix to our Babel command.

nr.config.js

export default ({ command }) => {
  command('compile', ['babel', ['src'], { outDir: 'dist' }], {
    prefix: chalk => chalk.bgYellow.black('Babel')
  })
};

execaOptions?: execa.Options

nr executes commands using execa. Here, you may provide any option accepted by execa to further fine-tune how the command is executed.

Example:

nr.config.js

export default ({ command }) => {
  command('compile', ['babel', ['src'], { outDir: 'dist' }], {
    execaOptions: {
      // Commands will inherit process.env, but additional variables can
      // be set here as well.
      env: {
        RAINBOWS: true,
        UNICORNS: true
      }
    }
  })
};

preserveArgumentCasing?: boolean

Default: false

Idiomatic JavaScript uses camel-case for object keys while the vast majority of CLIs accept named arguments in kebab-case. For this reason, nr automatically converts named arguments to kebab-case for you.

However, some CLIs (TypeScript, for example) expect named arguments to be in camel-case. To account for this, this option may be set to true to bypass automatic conversion of named arguments to kebab-case.

Example:

nr.config.js

export default ({ command }) => {
  command('tsc', ['tsc', { noEmit: true }], {
    preserveArgumentCasing: true
  })
};

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

When command is called, it creates a CommandThunk, a function that can be invoked to run the command. This function is added to a registry using the command's name, and then it is returned. There are two ways to reference a command in a script:

1. Use the CommandThunk directly in a script definition.

2. Use a string in the form cmd:name to instruct nr to look-up the command in the registry.

command.node

This variant of command is useful for commands where the executable is the node binary itself.

It has the same signature as command. It can be used to execute a Node script (regardless of whether the executable flag has been set on it) using the current version of Node. This variant uses execaNode to execute the script.

Example:

nr.config.js

export default ({ command }) => {
  // Equivalent to "node ./server.js" with some additional quality of
  // life enhancements provided by execaNode.
  command.node('server', ['./server.js'])
};

command.babel

This variant of command is useful for executing commands with babel-node.

It has the same signature as command. It can be used to execute a Node script (regardless of whether the executable flag has been set on it) using the babel-node CLI. This variant also uses execaNode to execute the script.

Example:

nr.config.js

export default ({ command }) => {
  // Equivalent to "babel-node --extensions=.ts,.tsx,.js,.jsx ./server.js"
  // with some additional quality of life enhancements provided by execaNode.
  command.babel('server', ['./server.js'])
};