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.

{
  "scripts": {
    "build": "tsc"
  }
}

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    }
  }
}

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:

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 same configuration and input files, then Wireit can copy the output from a cache, instead of running the command. This can significantly improve build and test time.

To enable caching for a script, ensure you have defined both the files and output arrays.

ℹ️ If a script doesn't produce any output files, it can still be cached by setting output to an empty array ("output": []). Empty output is common for tests, and is useful because it allows you to skip running tests if they previously passed with the exact same inputs.

Local caching

In local mode, Wireit caches output files to the .wireit folder inside each of your packages.

Local caching is enabled by default, unless the CI=true environment variable is detected. To force local caching, set WIREIT_CACHE=local. To disable local caching, set WIREIT_CACHE=none.

⚠️ Wireit does not currently limit the size of local caches. To free up this space, use rm -rf .wireit/*/cache. Automatic cache size limits will be added in an upcoming release, tracked at wireit#71.

GitHub Actions caching

In GitHub Actions mode, Wireit caches output files to the GitHub Actions cache service. This service is available whenever running in GitHub Actions, and is free for all GitHub users.

ℹ️ GitHub Actions cache entries are automatically deleted after 7 days, or if total usage exceeds 10 GB (the least recently used cache entry is deleted first). See the GitHub Actions documentation for more details.

To enable caching on GitHub Actions, add the following uses clause to your workflow. It can appear anywhere before the first npm run or npm test command:

- uses: google/wireit@setup-github-actions-caching/v2

Example workflow

# File: .github/workflows/tests.yml
name: Tests
on: [push, pull_request]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      # Set up GitHub Actions caching for Wireit.
      - uses: google/wireit@setup-github-actions-caching/v2
      # Install npm dependencies.
      - run: npm ci
      # Run tests. Wireit will automatically use
      # the GitHub Actions cache whenever possible.
      - run: npm test

Cleaning output

Wireit can automatically delete output files from previous runs before executing a script. This is helpful for ensuring that every build is clean and free from outdated files created in previous runs from source files that have since been removed.

Cleaning is enabled by default as long as the output array is defined. To change this behavior, set the wireit.<script>.clean property to one of these values:

Watch mode

In watch mode, Wireit monitors all files of a script, and all files of its transitive dependencies, and when there is a change, it re-runs only the affected scripts. To enable watch mode, first ensure that the files array is defined, and then run: