concurrently

Run multiple commands concurrently. Like npm run watch-js & npm run watch-less but better.

Table of Contents

• concurrently
  • Why
  • Installation
  • Usage
  • API
    • concurrently(commands[, options])
    • Command
    • CloseEvent
  • FAQ

Why

I like task automation with npm but the usual way to run multiple commands concurrently is npm run watch-js & npm run watch-css. That's fine but it's hard to keep on track of different outputs. Also if one process fails, others still keep running and you won't even notice the difference.

Another option would be to just run all commands in separate terminals. I got tired of opening terminals and made concurrently.

Features:

• Cross platform (including Windows)
• Output is easy to follow with prefixes
• With --kill-others switch, all commands are killed if one dies

Installation

concurrently can be installed in the global scope (if you'd like to have it available and use it on the whole system) or locally for a specific package (for example if you'd like to use it in the scripts section of your package):

| | npm | Yarn | pnpm | Bun | | ----------- | ----------------------- | ------------------------------ | -------------------------- | ------------------------- | | Global | npm i -g concurrently | yarn global add concurrently | pnpm add -g concurrently | bun add -g concurrently | | Local* | npm i -D concurrently | yarn add -D concurrently | pnpm add -D concurrently | bun add -d concurrently |

_{* It's recommended to add concurrently to devDependencies as it's usually used for developing purposes. Please adjust the command if this doesn't apply in your case.}

Usage

Note The concurrently command is also available under the shorthand alias conc.

The tool is written in Node.js, but you can use it to run any commands.

Remember to surround separate commands with quotes:

concurrently 'command1 arg' 'command2 arg'

Otherwise concurrently would try to run 4 separate commands: command1, arg, command2, arg.

[!IMPORTANT] Windows only supports double quotes:

concurrently "command1 arg" "command2 arg"

Remember to escape the double quotes in your package.json when using Windows:

"start": "concurrently \"command1 arg\" \"command2 arg\""

You can always check concurrently's flag list by running concurrently --help. For the version, run concurrently --version.

Check out documentation and other usage examples in the docs directory.

API

concurrently can be used programmatically by using the API documented below:

concurrently(commands[, options])

• commands: an array of either strings (containing the commands to run) or objects with the shape { command, name, prefixColor, env, cwd, ipc }.

• options (optional): an object containing any of the below:

  • cwd: the working directory to be used by all commands. Can be overridden per command. Default: process.cwd().
  • defaultInputTarget: the default input target when reading from inputStream. Default: 0.
  • handleInput: when true, reads input from process.stdin.
  • inputStream: a Readable stream to read the input from. Should only be used in the rare instance you would like to stream anything other than process.stdin. Overrides handleInput.
  • pauseInputStreamOnFinish: by default, pauses the input stream (process.stdin when handleInput is enabled, or inputStream if provided) when all of the processes have finished. If you need to read from the input stream after concurrently has finished, set this to false. (#252).
  • killOthersOn: once the first command exits with one of these statuses, kill other commands. Can be an array containing the strings success (status code zero) and/or failure (non-zero exit status).
  • maxProcesses: how many processes should run at once.
  • outputStream: a Writable stream to write logs to. Default: process.stdout.
  • prefix: the prefix type to use when logging processes output. Possible values: index, pid, time, command, name, none, or a template (eg [{time} process: {pid}]). Default: the name of the process, or its index if no name is set.
  • prefixColors: a list of colors or a string as supported by Chalk and additional style auto for an automatically picked color. If concurrently would run more commands than there are colors, the last color is repeated, unless if the last color value is auto which means following colors are automatically picked to vary. Prefix colors specified per-command take precedence over this list.
  • prefixLength: how many characters to show when prefixing with command. Default: 10
  • raw: whether raw mode should be used, meaning strictly process output will be logged, without any prefixes, coloring or extra stuff. Can be overridden per command.
  • successCondition: the condition to consider the run was successful. If first, only the first process to exit will make up the success of the run; if last, the last process that exits will determine whether the run succeeds. Anything else means all processes should exit successfully.
  • restartTries: how many attempts to restart a process that dies will be made. Default: 0.
  • restartDelay: how many milliseconds to wait between process restarts. Default: 0.
  • timestampFormat: a Unicode format to use when prefixing with time. Default: yyyy-MM-dd HH:mm:ss.SSS
  • additionalArguments: list of additional arguments passed that will get replaced in each command. If not defined, no argument replacing will happen.

Returns: an object in the shape { result, commands }.

• result: a Promise that resolves if the run was successful (according to successCondition option), or rejects, containing an array of CloseEvent, in the order that the commands terminated.
• commands: an array of all spawned Commands.

Example:

const concurrently = require('concurrently');
const { result } = concurrently(
  [
    'npm:watch-*',
    { command: 'nodemon', name: 'server' },
    { command: 'deploy', name: 'deploy', env: { PUBLIC_KEY: '...' } },
    {
      command: 'watch',
      name: 'watch',
      cwd: path.resolve(__dirname, 'scripts/watchers'),
    },
  ],
  {
    prefix: 'name',
    killOthersOn: ['failure', 'success'],
    restartTries: 3,
    cwd: path.resolve(__dirname, 'scripts'),
  },
);
result.then(success, failure);

Command

An object that contains all information about a spawned command, and ways to interact with it.<br> It has the following properties:

• index: the index of the command among all commands spawned.

• command: the command line of the command.

• name: the name of the command; defaults to an empty string.

• cwd: the current working directory of the command.

• env: an object with all the environment variables that the command will be spawned with.

• killed: whether the command has been killed.

• state: the command's state. Can be one of

  • stopped: if the command was never started
  • started: if the command is currently running
  • errored: if the command failed spawning
  • exited: if the command is not running anymore, e.g. it received a close event

• pid: the command's process ID.

• stdin: a Writable stream to the command's stdin.

• stdout: an RxJS observable to the command's stdout.

• stderr: an RxJS observable to the command's stderr.

• error: an RxJS observable to the command's error events (e.g. when it fails to spawn).

• timer: an RxJS observable to the command's timing events (e.g. starting, stopping).

• stateChange: an RxJS observable for changes to the command's state property.

• messages: an object with the following properties:

  • incoming: an RxJS observable for the IPC messages received from the underlying process.
  • outgoing: an RxJS observable for the IPC messages sent to the underlying process.

  Both observables emit MessageEvents.<br> Note that if the command wasn't spawned with IPC support, these won't emit any values.

• close: an RxJS observable to the command's close events. See CloseEvent for m