Wireit

<div align="center"> <img src="wireit.svg" height="125" alt="wireit"/>

Wireit upgrades your npm scripts to make them smarter and more efficient.

</div>

Features

• 🙂 Use the npm run commands you already know
• ⛓️ Automatically run dependencies between npm scripts in parallel
• 👀 Watch any script and continuously re-run on changes
• 🥬 Skip scripts that are already fresh
• ♻️ Cache output locally and remotely on GitHub Actions for free
• 🛠️ Works with single packages, npm workspaces, and other monorepos
• ✏️ VSCode plugin gives suggestions, documentation, and warnings as you develop

Contents

• Features
• Install
• Setup
• VSCode Extension
• Discord
• Dependencies
  • Vanilla scripts
  • Cross-package dependencies
• Parallelism
• Extra arguments
• Input and output files
  • Example configuration
  • Default excluded paths
• Incremental build
• Caching
  • Local caching
  • GitHub Actions caching
• Cleaning output
• Watch mode
• Services
• Execution cascade
• Environment variables
• Failures and errors
• Package locks
• Recipes
  • TypeScript
  • ESLint
• Reference
  • Configuration
  • Dependency syntax
  • Environment variable reference
  • Glob patterns
  • Fingerprint
• Requirements
• Related tools
• Contributing

Install

npm i -D wireit

Setup

Wireit works with npm run, it doesn't replace it. To configure an NPM script for Wireit, move the command into a new wireit section of your package.json, and replace the original script with the wireit command.

<table> <tr> <th>Before</th> <th>After</th> </tr> <tr> <td> <pre lang="json"> { "scripts": { "build": "tsc" } } </pre> </td> <td> <pre lang="json"> { "scripts": { "build": "wireit" }, "wireit": { "build": { "command": "tsc" } } } </pre> </td> </tr> </table>

Now when you run npm run build, Wireit upgrades the script to be smarter and more efficient. Wireit also works with node --run, yarn, and pnpm.

You should also add .wireit to your .gitignore file. Wireit uses the .wireit directory to store caches and other data for your scripts.

echo .wireit >> .gitignore

VSCode Extension

If you use VSCode, consider installing the google.wireit extension. It adds documentation on hover, autocomplete, can diagnose a number of common mistakes, and even suggest a refactoring to convert an npm script to use wireit.

Install it from the marketplace or on the command line like:

code --install-extension google.wireit

Discord

Join the Wireit Discord to chat with the Wireit community and get support for your project.

Dependencies

To declare a dependency between two scripts, edit the wireit.<script>.dependencies list:

{
  "scripts": {
    "build": "wireit",
    "bundle": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    },
    "bundle": {
      "command": "rollup -c",
      "dependencies": ["build"]
    }
  }
}

Now when you run npm run bundle, the build script will automatically run first.

Vanilla scripts

The scripts you depend on don't need to be configured for Wireit, they can be vanilla npm scripts. This lets you only use Wireit for some of your scripts, or to upgrade incrementally. Scripts that haven't been configured for Wireit are always safe to use as dependencies; they just won't be fully optimized.

Wireit-only scripts

It is valid to define a script in the wireit section that is not in the scripts section, but such scripts can only be used as dependencies from other wireit scripts, and can never be run directly.

Cross-package dependencies

Dependencies can refer to scripts in other npm packages by using a relative path with the syntax <relative-path>:<script-name>. All cross-package dependencies should start with a ".". Cross-package dependencies work well for npm workspaces, as well as in other kinds of monorepos.

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "dependencies": ["../other-package:build"]
    }
  }
}

Parallelism

Wireit will run scripts in parallel whenever it is safe to do so according to the dependency graph.

For example, in this diagram, the B and C scripts will run in parallel, while the A script won't start until both B and C finish.

graph TD
  A-->B;
  A-->C;
  subgraph parallel
    B;
    C;
  end

By default, Wireit will run up to 2 scripts in parallel for every logical CPU core detected on your system. To change this default, set the WIREIT_PARALLEL environment variable to a positive integer, or infinity to run without a limit. You may want to lower this number if you experience resource starvation in large builds. For example, to run only one script at a time:

export WIREIT_PARALLEL=1
npm run build

If two or more separate npm run commands are run for the same Wireit script simultaneously, then only one instance will be allowed to run at a time, while the others wait their turn. This prevents coordination problems that can result in incorrect output files being produced. If output is set to an empty array, then this restriction is removed.

Extra arguments

As with plain npm scripts, you can pass extra arguments to a Wireit script by placing a -- double-dash argument in front of them. Any arguments after a -- are sent to the underlying command, instead of being interpreted as arguments to npm or Wireit:

npm run build -- --verbose

Or in general:

npm run {script} {npm args} {wireit args} -- {script args}

An additional -- is required when using node --run in order to distinguish between arguments intended for node, wireit, and the script itself:

node --run {script} {node args} -- {wireit args} -- {script args}

Input and output files

The files and output properties of wireit.<script> tell Wireit what your script's input and output files are, respectively. They should be arrays of glob patterns, where paths are interpreted relative to the package directory. They can be set on some, all, or none of your scripts.

Setting these properties allow you to use more features of Wireit:

| | Requires<br>files | Requires<br>output | | ------------------------------------------: | :-----------------: | :------------------: | | Dependency graph | - | - | | Watch mode | ☑️ | - | | Clean build | - | ☑️ | | Incremental build | ☑️ | ☑️ | | Caching | ☑️ | ☑️ |

Example configuration

{
  "scripts": {
    "build": "wireit",
    "bundle": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"]
    },
    "bundle": {
      "command": "rollup -c",
      "dependencies": ["build"],
      "files": ["rollup.config.json"],
      "output": ["dist/bundle.js"]
    }
  }
}

Default excluded paths

By default, the following folders are excluded from the files and output arrays:

• .git/
• .hg/
• .svn/
• .wireit/
• .yarn/
• CVS/
• node_modules/

In the highly unusual case that you need to reference a file in one of those folders, set allowUsuallyExcludedPaths: true to remove all default excludes.

Incremental build

Wireit can automatically skip execution of a script if nothing has changed that would cause it to produce different output since the last time it ran. This is called incremental build.

To enable incremental build, configure the input and output files for each script by specifying glob patterns in the wireit.<script>.files and wireit.<script>.output arrays.

ℹ️ If a script doesn't have a files or output list defined at all, then it will always run, because Wireit doesn't know which files to check for changes. To tell Wireit it is safe to skip execution of a script that definitely has no input and/or files, set files and/or output to an empty array (files: [], output: []).

Caching

If a script has previously succeeded with the sa