{"id":13457645,"url":"https://github.com/google/wireit","last_synced_at":"2025-03-24T14:32:10.371Z","repository":{"id":37077833,"uuid":"440909617","full_name":"google/wireit","owner":"google","description":"Wireit upgrades your npm/pnpm/yarn scripts to make them smarter and more efficient.","archived":false,"fork":false,"pushed_at":"2025-03-10T22:37:49.000Z","size":5666,"stargazers_count":6186,"open_issues_count":105,"forks_count":109,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-03-22T00:42:49.813Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-22T15:52:53.000Z","updated_at":"2025-03-21T00:55:16.000Z","dependencies_parsed_at":"2024-02-16T03:27:07.049Z","dependency_job_id":"e2ff1c11-8c7f-40f8-9081-22e7ed32b162","html_url":"https://github.com/google/wireit","commit_stats":{"total_commits":737,"total_committers":18,"mean_commits":40.94444444444444,"dds":"0.38127544097693356","last_synced_commit":"29481217e7e3ba74be93c63dc5608bc779a484b7"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fwireit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fwireit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fwireit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fwireit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/wireit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245019621,"owners_count":20548147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T09:00:32.804Z","updated_at":"2025-03-24T14:32:10.354Z","avatar_url":"https://github.com/google.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"wireit.svg\" height=\"125\" alt=\"wireit\"/\u003e\n\n_Wireit upgrades your npm scripts to make them smarter and more efficient._\n\n[![Published on npm](https://img.shields.io/npm/v/wireit.svg?logo=npm)](https://www.npmjs.com/package/wireit)\n[![Build Status](https://github.com/google/wireit/actions/workflows/tests.yml/badge.svg)](https://github.com/google/wireit/actions/workflows/tests.yml)\n[![Discord](https://discordapp.com/api/guilds/1036766782867914792/widget.png?style=shield)](https://discord.gg/chmdAwvq4e)\n\n\u003c/div\u003e\n\n## Features\n\n- 🙂 Use the `npm run` commands you already know\n- ⛓️ Automatically run dependencies between npm scripts in parallel\n- 👀 Watch any script and continuously re-run on changes\n- 🥬 Skip scripts that are already fresh\n- ♻️ Cache output locally and remotely on GitHub Actions for free\n- 🛠️ Works with single packages, npm workspaces, and other monorepos\n- ✏️ [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=google.wireit) gives suggestions, documentation, and warnings as you develop\n\n## Contents\n\n- [Features](#features)\n- [Install](#install)\n- [Setup](#setup)\n- [VSCode Extension](#vscode-extension)\n- [Discord](#discord)\n- [Dependencies](#dependencies)\n  - [Vanilla scripts](#vanilla-scripts)\n  - [Cross-package dependencies](#cross-package-dependencies)\n- [Parallelism](#parallelism)\n- [Extra arguments](#extra-arguments)\n- [Input and output files](#input-and-output-files)\n  - [Example configuration](#example-configuration)\n  - [Default excluded paths](#default-excluded-paths)\n- [Incremental build](#incremental-build)\n- [Caching](#caching)\n  - [Local caching](#local-caching)\n  - [GitHub Actions caching](#github-actions-caching)\n- [Cleaning output](#cleaning-output)\n- [Watch mode](#watch-mode)\n- [Services](#services)\n- [Execution cascade](#execution-cascade)\n- [Environment variables](#environment-variables)\n- [Failures and errors](#failures-and-errors)\n- [Package locks](#package-locks)\n- [Recipes](#recipes)\n  - [TypeScript](#typescript)\n  - [ESLint](#eslint)\n- [Reference](#reference)\n  - [Configuration](#configuration)\n  - [Dependency syntax](#dependency-syntax)\n  - [Environment variable reference](#environment-variable-reference)\n  - [Glob patterns](#glob-patterns)\n  - [Fingerprint](#fingerprint)\n- [Requirements](#requirements)\n- [Related tools](#related-tools)\n- [Contributing](#contributing)\n\n## Install\n\n```sh\nnpm i -D wireit\n```\n\n## Setup\n\nWireit works _with_ `npm run`, it doesn't replace it. To configure an NPM script\nfor Wireit, move the command into a new `wireit` section of your `package.json`,\nand replace the original script with the `wireit` command.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eBefore\u003c/th\u003e\n\u003cth\u003eAfter\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003cpre lang=\"json\"\u003e\n{\n  \"scripts\": {\n    \"build\": \"tsc\"\n  }\n}\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cpre lang=\"json\"\u003e\n{\n  \"scripts\": {\n    \"build\": \"wireit\"\n  },\n  \"wireit\": {\n    \"build\": {\n      \"command\": \"tsc\"\n    }\n  }\n}\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nNow when you run `npm run build`, Wireit upgrades the script to be smarter and\nmore efficient. Wireit also works with [`node --run`](https://nodejs.org/en/blog/announcements/v22-release-announce#running-packagejson-scripts), [yarn](https://yarnpkg.com/), and [pnpm](https://pnpm.io/).\n\nYou should also add `.wireit` to your `.gitignore` file. Wireit uses the\n`.wireit` directory to store caches and other data for your scripts.\n\n```sh\necho .wireit \u003e\u003e .gitignore\n```\n\n## VSCode Extension\n\nIf 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.\n\nInstall it [from the marketplace](https://marketplace.visualstudio.com/items?itemName=google.wireit) or on the command line like:\n\n```sh\ncode --install-extension google.wireit\n```\n\n## Discord\n\nJoin the [Wireit Discord](https://discord.gg/chmdAwvq4e) to chat with the Wireit community and get support for your project.\n\n[![Discord](https://discordapp.com/api/guilds/1036766782867914792/widget.png?style=banner2)](https://discord.gg/chmdAwvq4e)\n\n## Dependencies\n\nTo declare a dependency between two scripts, edit the\n`wireit.\u003cscript\u003e.dependencies` list:\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"wireit\",\n    \"bundle\": \"wireit\"\n  },\n  \"wireit\": {\n    \"build\": {\n      \"command\": \"tsc\"\n    },\n    \"bundle\": {\n      \"command\": \"rollup -c\",\n      \"dependencies\": [\"build\"]\n    }\n  }\n}\n```\n\nNow when you run `npm run bundle`, the `build` script will automatically run\nfirst.\n\n### Vanilla scripts\n\nThe scripts you depend on don't need to be configured for Wireit, they can be\nvanilla `npm` scripts. This lets you only use Wireit for some of your scripts,\nor to upgrade incrementally. Scripts that haven't been configured for Wireit are\nalways safe to use as dependencies; they just won't be fully optimized.\n\n### Wireit-only scripts\n\nIt is valid to define a script in the `wireit` section that is not in the\n`scripts` section, but such scripts can only be used as `dependencies` from\nother wireit scripts, and can never be run directly.\n\n### Cross-package dependencies\n\nDependencies can refer to scripts in other npm packages by using a relative path\nwith the syntax `\u003crelative-path\u003e:\u003cscript-name\u003e`. All cross-package dependencies\nshould start with a `\".\"`. Cross-package dependencies work well for npm\nworkspaces, as well as in other kinds of monorepos.\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"wireit\"\n  },\n  \"wireit\": {\n    \"build\": {\n      \"command\": \"tsc\",\n      \"dependencies\": [\"../other-package:build\"]\n    }\n  }\n}\n```\n\n## Parallelism\n\nWireit will run scripts in parallel whenever it is safe to do so according to\nthe dependency graph.\n\nFor example, in this diagram, the `B` and `C` scripts will run in parallel,\nwhile the `A` script won't start until both `B` and `C` finish.\n\n```mermaid\ngraph TD\n  A--\u003eB;\n  A--\u003eC;\n  subgraph parallel\n    B;\n    C;\n  end\n```\n\nBy default, Wireit will run up to 2 scripts in parallel for every logical CPU\ncore detected on your system. To change this default, set the `WIREIT_PARALLEL`\n[environment variable](#environment-variable-reference) to a positive integer, or\n`infinity` to run without a limit. You may want to lower this number if you\nexperience resource starvation in large builds. For example, to run only one\nscript at a time:\n\n```sh\nexport WIREIT_PARALLEL=1\nnpm run build\n```\n\nIf two or more separate `npm run` commands are run for the same Wireit script\nsimultaneously, then only one instance will be allowed to run at a time, while\nthe others wait their turn. This prevents coordination problems that can result\nin incorrect output files being produced. If `output` is set to an empty array,\nthen this restriction is removed.\n\n## Extra arguments\n\nAs with plain npm scripts, you can pass extra arguments to a Wireit script by\nplacing a `--` double-dash argument in front of them. Any arguments after a `--`\nare sent to the underlying command, instead of being interpreted as arguments to\nnpm or Wireit:\n\n```sh\nnpm run build -- --verbose\n```\n\nOr in general:\n\n```sh\nnpm run {script} {npm args} {wireit args} -- {script args}\n```\n\nAn additional `--` is required when using `node --run` in order to distinguish\nbetween arguments intended for `node`, `wireit`, and the script itself:\n\n```sh\nnode --run {script} {node args} -- {wireit args} -- {script args}\n```\n\n## Input and output files\n\nThe `files` and `output` properties of `wireit.\u003cscript\u003e` tell Wireit what your\nscript's input and output files are, respectively. They should be arrays of\n[glob patterns](#glob-patterns), where paths are interpreted relative to the\npackage directory. They can be set on some, all, or none of your scripts.\n\nSetting these properties allow you to use more features of Wireit:\n\n|                                             | Requires\u003cbr\u003e`files` | Requires\u003cbr\u003e`output` |\n| ------------------------------------------: | :-----------------: | :------------------: |\n|       [**Dependency graph**](#dependencies) |          -          |          -           |\n|               [**Watch mode**](#watch-mode) |         ☑️          |          -           |\n|         [**Clean build**](#cleaning-output) |          -          |          ☑️          |\n| [**Incremental build**](#incremental-build) |         ☑️          |          ☑️          |\n|                     [**Caching**](#caching) |         ☑️          |          ☑️          |\n\n### Example configuration\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"wireit\",\n    \"bundle\": \"wireit\"\n  },\n  \"wireit\": {\n    \"build\": {\n      \"command\": \"tsc\",\n      \"files\": [\"src/**/*.ts\", \"tsconfig.json\"],\n      \"output\": [\"lib/**\"]\n    },\n    \"bundle\": {\n      \"command\": \"rollup -c\",\n      \"dependencies\": [\"build\"],\n      \"files\": [\"rollup.config.json\"],\n      \"output\": [\"dist/bundle.js\"]\n    }\n  }\n}\n```\n\n### Default excluded paths\n\nBy default, the following folders are excluded from the `files` and `output`\narrays:\n\n- `.git/`\n- `.hg/`\n- `.svn/`\n- `.wireit/`\n- `.yarn/`\n- `CVS/`\n- `node_modules/`\n\nIn the highly unusual case that you need to reference a file in one of those\nfolders, set `allowUsuallyExcludedPaths: true` to remove all default excludes.\n\n## Incremental build\n\nWireit can automatically skip execution of a script if nothing has changed that\nwould cause it to produce different output since the last time it ran. This is\ncalled _incremental build_.\n\nTo enable incremental build, configure the input and output files for each\nscript by specifying [glob patterns](#glob-patterns) in the\n`wireit.\u003cscript\u003e.files` and `wireit.\u003cscript\u003e.output` arrays.\n\n\u003e ℹ️ If a script doesn't have a `files` or `output` list defined at all, then it\n\u003e will _always_ run, because Wireit doesn't know which files to check for\n\u003e changes. To tell Wireit it is safe to skip execution of a script that\n\u003e definitely has no input and/or files, set `files` and/or `output` to an empty\n\u003e array (`files: [], output: []`).\n\n## Caching\n\nIf a script has previously succeeded with the same configuration and input\nfiles, then Wireit can copy the output from a cache, instead of running the\ncommand. This can significantly improve build and test time.\n\nTo enable caching for a script, ensure you have defined both the [`files` and\n`output`](#input-and-output-files) arrays.\n\n\u003e ℹ️ If a script doesn't produce any output files, it can still be cached by\n\u003e setting `output` to an empty array (`\"output\": []`). Empty output is common for\n\u003e tests, and is useful because it allows you to skip running tests if they\n\u003e previously passed with the exact same inputs.\n\n### Local caching\n\nIn _local_ mode, Wireit caches `output` files to the `.wireit` folder inside\neach of your packages.\n\nLocal caching is enabled by default, unless the\n[`CI=true`](https://docs.github.com/en/enterprise-cloud@latest/actions/learn-github-actions/environment-variables#default-environment-variables)\nenvironment variable is detected. To force local caching, set\n`WIREIT_CACHE=local`. To disable local caching, set `WIREIT_CACHE=none`.\n\n\u003e ⚠️ Wireit does not currently limit the size of local caches. To free up this\n\u003e space, use `rm -rf .wireit/*/cache`. Automatic cache size limits will be added\n\u003e in an upcoming release, tracked at\n\u003e [wireit#71](https://github.com/google/wireit/issues/71).\n\n### GitHub Actions caching\n\nIn _[GitHub Actions](https://github.com/features/actions)_ mode, Wireit caches\n`output` files to the [GitHub Actions\ncache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)\nservice. This service is available whenever running in GitHub Actions, and is\nfree for all GitHub users.\n\n\u003e ℹ️ GitHub Actions cache entries are automatically deleted after 7 days, or if\n\u003e total usage exceeds 10 GB (the least recently used cache entry is deleted\n\u003e first). See the [GitHub Actions\n\u003e documentation](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)\n\u003e for more details.\n\nTo enable caching on GitHub Actions, add the following\n[`uses`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses)\nclause to your workflow. It can appear anywhere before the first `npm run` or\n`npm test` command:\n\n```yaml\n- uses: google/wireit@setup-github-actions-caching/v2\n```\n\n#### Example workflow\n\n```yaml\n# File: .github/workflows/tests.yml\n\nname: Tests\non: [push, pull_request]\njobs:\n  tests:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: 18\n          cache: npm\n\n      # Set up GitHub Actions caching for Wireit.\n      - uses: google/wireit@setup-github-actions-caching/v2\n\n      # Install npm dependencies.\n      - run: npm ci\n\n      # Run tests. Wireit will automatically use\n      # the GitHub Actions cache whenever possible.\n      - run: npm test\n```\n\n## Cleaning output\n\nWireit can automatically delete output files from previous runs before executing\na script. This is helpful for ensuring that every build is clean and free from\noutdated files created in previous runs from source files that have since been\nremoved.\n\nCleaning is enabled by default as long as the\n[`output`](#input-and-output-files) array is defined. To change this behavior,\nset the `wireit.\u003cscript\u003e.clean` property to one of these values:\n\n| Setting             | Description                                                                                                                                                                                                                                                                                     |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `true`              | Clean before every run (the default).                                                                                                                                                                                                                                                           |\n| `\"if-file-deleted\"` | Clean only if an input file has been deleted since the last run.\u003cbr\u003e\u003cbr\u003eUse this option for tools that have incremental build support, but do not clean up outdated output when a source file has been deleted, such as `tsc --build` (see [TypeScript](#typescript) for more on this example.) |\n| `false`             | Do not clean.\u003cbr\u003e\u003cbr\u003eOnly use this option if you are certain that the script command itself already takes care of removing outdated files from previous runs.                                                                                                                                   |\n\n## Watch mode\n\nIn _watch_ mode, Wireit monitors all `files` of a script, and all `files` of its\ntransitive dependencies, and when there is a change, it re-runs only the\naffected scripts. To enable watch mode, ensure that the\n[`files`](#input-and-output-files) array is defined, and add the `--watch`\nflag:\n\n```sh\nnpm run \u003cscript\u003e --watch\n```\n\nAn additional `--` is required when using `node --run`, otherwise Node's\nbuilt-in [watch](https://nodejs.org/docs/v20.17.0/api/cli.html#--watch) feature\nwill be triggered instead of Wireit's:\n\n```sh\nnode --run \u003cscript\u003e -- --watch\n```\n\nThe benefit of Wireit's watch mode over the built-in watch modes of Node and other programs are:\n\n- Wireit watches the entire dependency graph, so a single watch command replaces\n  many built-in ones.\n- It prevents problems that can occur when running many separate watch commands\n  simultaneously, such as build steps being triggered before all preceding steps\n  have finished.\n\nBy default, watch mode uses whichever filesystem change API is available on your\nOS. This behavior can be changed with the `WIREIT_WATCH_STRATEGY` and\n`WIREIT_WATCH_POLL_MS` environment variables (see\n[below](#environment-variable-reference)).\n\n## Environment variables\n\nUse the `env` setting to either directly set environment variables, or to\nindicate that an externally-defined environment variable affects the behavior of\na script.\n\n### Setting environment variables directly\n\nIf a property value in the `env` object is a string, then that environment\nvariable will be set to that value when the script's `command` runs,\noverriding any value from the parent process.\n\nUnlike built-in shell environment variable syntaxes, using `env` to set\nenvironment variables works the same in macOS/Linux vs Windows, and in all\nshells.\n\n\u003e **Note** Setting an environment variable with `env` does not apply\n\u003e transitively through dependencies. If you need the same environment variable\n\u003e to be set for multiple scripts, you must configure it for each of them.\n\n```json\n{\n  \"wireit\": {\n    \"my-script\": {\n      \"command\": \"my-command\",\n      \"env\": {\n        \"MY_VARIABLE\": \"my value\"\n      }\n    }\n  }\n}\n```\n\n### Indicating external environment variables\n\nIf an environment variable affects the behavior of a script but is set\n_externally_ (i.e. it is passed to the `wireit` parent process), set the `env`\nproperty to `{\"external\": true}`. This tells Wireit that if the value of an\nenvironment variable changes across executions of a script, then its output\nshould not be re-used. You may also set a `default` value for the variable\nto use when none is provided externally.\n\n```json\n{\n  \"wireit\": {\n    \"my-script\": {\n      \"command\": \"my-command\",\n      \"env\": {\n        \"MY_VARIABLE\": {\n          \"external\": true\n        },\n        \"MY_VARIABLE_2\": {\n          \"external\": true,\n          \"default\": \"foo\"\n        }\n      }\n    }\n  }\n}\n```\n\n## Services\n\nBy default, Wireit assumes that your scripts will eventually exit by themselves.\nThis is well suited for build and test scripts, but not for long-running\nprocesses like servers. To tell Wireit that a process is long-running and not\nexpected to exit by itself, set `\"service\": true`.\n\n```json\n{\n  \"scripts\": {\n    \"start\": \"wireit\",\n    \"build:server\": \"wireit\"\n  },\n  \"wireit\": {\n    \"start\": {\n      \"command\": \"node my-server.js\",\n      \"service\": true,\n      \"files\": [\"my-server.js\"],\n      \"dependencies\": [\n        \"build:server\",\n        {\n          \"script\": \"../assets:build\",\n          \"cascade\": false\n        }\n      ]\n    },\n    \"build:server\": {\n      ...\n    }\n  }\n}\n```\n\n### Service lifetime\n\nIf a service is run _directly_ (e.g. `npm run serve`), then it will stay running\nuntil the user kills Wireit (e.g. `Ctrl-C`).\n\nIf a service is a _dependency_ of one or more other scripts, then it will start\nup before any depending script runs, and will shut down after all depending\nscripts finish.\n\n### Service readiness\n\nBy default, a service is considered _ready_ as soon as its process spawns,\nallowing any scripts that depend on that service to start.\n\nHowever, often times a service needs to perform certain actions before it is\nsafe for dependents to interact with it, such as starting a server and listening\non a network interface.\n\nUse `service.readyWhen.lineMatches` to tell Wireit to monitor the `stdout` and\n`stderr` of the service and defer readiness until a line is printed that matches\nthe given regular expression.\n\n```json\n{\n  \"command\": \"node my-server.js\",\n  \"service\": {\n    \"readyWhen\": {\n      \"lineMatches\": \"Server listening on port \\\\d+\"\n    }\n  }\n}\n```\n\n### Service restarts\n\nIn watch mode, a service will be restarted whenever one of its input files or\ndependencies change, except for dependencies with\n[`cascade`](#execution-cascade) set to `false`.\n\n### Service output\n\nServices cannot have `output` files, because there is no way for Wireit to know\nwhen a service has finished writing its output.\n\nIf you have a service that produces output, you should define a _non-service_\nscript that depends on it, and which exits when the service's output is\ncomplete.\n\n## Execution cascade\n\nBy default, a script always needs to run (or restart in the case of\n[`services`](#services)) if any of its dependencies needed to run, _regardless\nof whether the dependency produced new or relevant output_.\n\nThis automatic _cascade_ of script execution is the default behavior because it\nensures that any _possible_ output produced by a dependent script propagates to all other\nscripts that might depend on it. In other words, Wireit does not assume that the\n`files` array completely describes the inputs to a script with dependencies.\n\n### Disabling cascade\n\nThis execution cascade behavior can be disabled by expanding a dependency into\nan object, and setting the `cascade` property to `false`:\n\n\u003e **Note**\n\u003e What really happens under the hood is that the `cascade` property simply controls\n\u003e whether the [fingerprint](#fingerprint) of a script _includes the fingerprints\n\u003e of its dependencies_, which in turn determines whether a script needs to run or restart.\n\n```json\n{\n  \"dependencies\": [\n    {\n      \"script\": \"foo\",\n      \"cascade\": false\n    }\n  ]\n}\n```\n\n### Reasons to disable cascade\n\nThere are two main reasons you might want to set `cascade` to `false`:\n\n1. **Your script only consumes a subset of a dependency's output.**\n\n   For example, `tsc` produces both `.js` files and `.d.ts` files, but only the\n   `.js` files might be consumed by `rollup`. There is no need to re-bundle\n   when a typings-only changed occurred.\n\n   \u003e **Note**\n   \u003e In addition to setting `cascade` to `false`, the subset of output that\n   \u003e _does_ matter (`lib/**/*.js`) has been added to the `files` array.\n\n   ```json\n   {\n     \"scripts\": {\n       \"build\": \"wireit\",\n       \"bundle\": \"wireit\"\n     },\n     \"wireit\": {\n       \"build\": {\n         \"command\": \"tsc\",\n         \"files\": [\"src/**/*.ts\", \"tsconfig.json\"],\n         \"output\": [\"lib/**\"]\n       },\n       \"bundle\": {\n         \"command\": \"rollup -c\",\n         \"dependencies\": [\n           {\n             \"script\": \"build\",\n             \"cascade\": false\n           }\n         ],\n         \"files\": [\"rollup.config.json\", \"lib/**/*.js\"],\n         \"output\": [\"dist/bundle.js\"]\n       }\n     }\n   }\n   ```\n\n2. **Your server doesn't need to restart for certain changes.**\n\n   For example, a web server depends on some static assets, but the server\n   reads those assets from disk dynamically on each request. In [`watch`](#watch-mode) mode,\n   there is no need to restart the server when the assets change.\n\n   \u003e **Note**\n   \u003e The `build:server` dependency uses the default `cascade` behavior\n   \u003e (`true`), because changing the implementation of the server itself _does_\n   \u003e require the server to be restarted.\n\n   ```json\n   {\n     \"scripts\": {\n       \"start\": \"wireit\",\n       \"build:server\": \"wireit\"\n     },\n     \"wireit\": {\n       \"start\": {\n         \"command\": \"node lib/server.js\",\n         \"service\": true,\n         \"dependencies\": [\n           \"build:server\",\n           {\n             \"script\": \"../assets:build\",\n             \"cascade\": false\n           }\n         ],\n         \"files\": [\"lib/**/*.js\"]\n       },\n       \"build:server\": {\n         \"command\": \"tsc\",\n         \"files\": [\"src/**/*.ts\", \"tsconfig.json\"],\n         \"output\": [\"lib/**\"]\n       }\n     }\n   }\n   ```\n\n## Failures and errors\n\nBy default, when a script fails (meaning it returned with a non-zero exit code),\nall scripts that are already running are allowed to finish, but new scripts are\nnot started.\n\nIn some situations a different behavior may be better suited. There are 2\nadditional modes, which you can set with the `WIREIT_FAILURES` environment\nvariable. Note that Wireit always ultimately exits with a non-zero exit code if\nthere was a failure, regardless of the mode.\n\n### Continue\n\nWhen a failure occurs in `continue` mode, running scripts continue, and new\nscripts are started as long as the failure did not affect their dependencies.\nThis mode is useful if you want a complete picture of which scripts are\nsucceeding and which are failing.\n\n```bash\nWIREIT_FAILURES=continue\n```\n\n### Kill\n\nWhen a failure occurs in `kill` mode, running scripts are immediately killed,\nand new scripts are not started. This mode is useful if you want to be notified\nas soon as possible about any failures.\n\n```bash\nWIREIT_FAILURES=kill\n```\n\n## Package locks\n\nBy default, Wireit automatically treats package manager lock files as input\nfiles\n([`package-lock.json`](https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json)\nfor npm and `node --run`,\n[`yarn.lock`](https://yarnpkg.com/configuration/yarnrc#lockfileFilename) for\nyarn, and [`pnpm-lock.yaml`](https://pnpm.io/git#lockfiles) for pnpm). Wireit\nwill look for these lock files in the script's package, and all parent\ndirectories.\n\nThis is useful because installing or upgrading your dependencies can affect the\nbehavior of your scripts, so it's important to re-run them whenever your\ndependencies change.\n\nTo change the name of the package lock file Wireit should look for, specify it\nin the `wireit.\u003cscript\u003e.packageLocks` array. You can specify multiple filenames\nhere, if needed.\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"wireit\"\n  },\n  \"wireit\": {\n    \"build\": {\n      \"command\": \"tsc\",\n      \"files\": [\"src/**/*.ts\", \"tsconfig.json\"],\n      \"output\": [\"lib/**\"],\n      \"packageLocks\": [\"another-package-manager.lock\"]\n    }\n  }\n}\n```\n\nIf you're sure that a script isn't affected by dependencies at all, you can turn\noff this behavior entirely to improve your cache hit rate by setting\n`wireit.\u003cscript\u003e.packageLocks` to `[]`.\n\n## Recipes\n\nThis section contains advice about integrating specific build tools with Wireit.\n\n### TypeScript\n\n```json\n{\n  \"scripts\": {\n    \"ts\": \"wireit\"\n  },\n  \"wireit\": {\n    \"ts\": {\n      \"command\": \"tsc --build --pretty\",\n      \"clean\": \"if-file-deleted\",\n      \"files\": [\"src/**/*.ts\", \"tsconfig.json\"],\n      \"output\": [\"lib/**\", \".tsbuildinfo\"]\n    }\n  }\n}\n```\n\n- Set [`\"incremental\": true`](https://www.typescriptlang.org/tsconfig#incremental) and use\n  [`--build`](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript)\n  to enable incremental compilation, which significantly improves performance.\n- Include\n  [`.tsbuildinfo`](https://www.typescriptlang.org/tsconfig#tsBuildInfoFile) in\n  `output` so that it is reset on clean builds. Otherwise `tsc` will get out of\n  sync and produce incorrect output.\n- Set [`\"clean\": \"if-file-deleted\"`](#cleaning-output) so that you get fast\n  incremental compilation when sources are changed/added, but also stale outputs\n  are cleaned up when a source is deleted (`tsc` does not clean up stale outputs\n  by itself).\n- Include `tsconfig.json` in `files` so that changing your configuration re-runs\n  `tsc`.\n- Use [`--pretty`](https://www.typescriptlang.org/tsconfig#pretty) to get\n  colorful output despite not being attached to a TTY.\n\n### ESLint\n\n```json\n{\n  \"scripts\": {\n    \"lint\": \"wireit\"\n  },\n  \"wireit\": {\n    \"lint\": {\n      \"command\": \"eslint --color --cache --cache-location .eslintcache .\",\n      \"files\": [\"src/**/*.ts\", \".eslintignore\", \".eslintrc.cjs\"],\n      \"output\": []\n    }\n  }\n}\n```\n\n- Use\n  [`--cache`](https://eslint.org/docs/user-guide/command-line-interface#caching)\n  so that `eslint` only lints the files that were added or changed since the\n  last run, which significantly improves performance.\n- Use\n  [`--color`](https://eslint.org/docs/user-guide/command-line-interface#--color---no-color)\n  to get colorful output despite not being attached to a TTY.\n- Include config and ignore files in `files` so that changing your configuration\n  re-runs `eslint`.\n\n## Reference\n\n### Configuration\n\nThe following properties can be set inside `wireit.\u003cscript\u003e` objects in\n`package.json` files:\n\n| Property                  | Type                               | Default                 | Description                                                                                                                     |\n| ------------------------- | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `command`                 | `string`                           | `undefined`             | The shell command to run.                                                                                                       |\n| `dependencies`            | `string[] \\| object[]`             | `[]`                    | [Scripts that must run before this one](#dependencies).                                                                         |\n| `dependencies[i].script`  | `string`                           | `undefined`             | [The name of the script, when the dependency is an object.](#dependencies).                                                     |\n| `dependencies[i].cascade` | `boolean`                          | `true`                  | [Whether this dependency always causes this script to re-execute](#execution-cascade).                                          |\n| `files`                   | `string[]`                         | `undefined`             | Input file [glob patterns](#glob-patterns), used to determine the [fingerprint](#fingerprint).                                  |\n| `output`                  | `string[]`                         | `undefined`             | Output file [glob patterns](#glob-patterns), used for [caching](#caching) and [cleaning](#cleaning-output).                     |\n| `clean`                   | `boolean \\| \"if-file-deleted\"`     | `true`                  | [Delete output files before running](#cleaning-output).                                                                         |\n| `env`                     | `Record\u003cstring, string \\| object\u003e` | `false`                 | [Environment variables](#environment-variables) to set when running this command, or that are external and affect the behavior. |\n| `env[i].external`         | `true \\| undefined`                | `undefined`             | `true` if an [environment variable](#environment-variables) is set externally and affects the script's behavior.                |\n| `env[i].default`          | `string \\| undefined`              | `undefined`             | Default value to use when an external [environment variable](#environment-variables) is not provided.                           |\n| `service`                 | `boolean`                          | `false`                 | [Whether this script is long-running, e.g. a server](#cleaning-output).                                                         |\n| `packageLocks`            | `string[]`                         | `['package-lock.json']` | [Names of package lock files](#package-locks).                                                                                  |\n\n### Dependency syntax\n\nThe following syntaxes can be used in the `wireit.\u003cscript\u003e.dependencies` array:\n\n| Example      | Description                                                                                     |\n| ------------ | ----------------------------------------------------------------------------------------------- |\n| `foo`        | Script named `\"foo\"` in the same package.                                                       |\n| `../foo:bar` | Script named `\"bar\"` in the package found at `../foo` ([details](#cross-package-dependencies)). |\n\n### Environment variable reference\n\nThe following environment variables affect the behavior of Wireit:\n\n| Variable                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `WIREIT_CACHE`          | [Caching mode](#caching).\u003cbr\u003e\u003cbr\u003eDefaults to `local` unless `CI` is `true`, in which case defaults to `none`.\u003cbr\u003e\u003cbr\u003eAutomatically set to `github` by the [`google/wireit@setup-github-actions-caching/v2`](#github-actions-caching) action.\u003cbr\u003e\u003cbr\u003eOptions:\u003cul\u003e\u003cli\u003e[`local`](#local-caching): Cache to local disk.\u003c/li\u003e\u003cli\u003e[`github`](#github-actions-caching): Cache to GitHub Actions.\u003c/li\u003e\u003cli\u003e`none`: Disable caching.\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                                                      |\n| `WIREIT_FAILURES`       | [How to handle script failures](#failures-and-errors).\u003cbr\u003e\u003cbr\u003eOptions:\u003cbr\u003e\u003cul\u003e\u003cli\u003e[`no-new`](#failures-and-errors) (default): Allow running scripts to finish, but don't start new ones.\u003c/li\u003e\u003cli\u003e[`continue`](#continue): Allow running scripts to continue, and start new ones unless any of their dependencies failed.\u003c/li\u003e\u003cli\u003e[`kill`](#kill): Immediately kill running scripts, and don't start new ones.\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                                                                   |\n| `WIREIT_LOGGER`         | How to present progress and results on the command line.\u003cbr\u003e\u003cbr\u003eOptions:\u003cbr\u003e\u003cul\u003e\u003cli\u003e`quiet` (default for normal execution): Writes a single dynamically updating line summarizing progress. Only passes along stdout and stderr from commands if there's a failure, or if the command is a service.\u003c/li\u003e\u003cli\u003e`quiet-ci` (default when `env.CI` or `!stdout.isTTY`): like `quiet` but optimized for non-interactive environments, like GitHub Actions runners.\u003c/li\u003e\u003cli\u003e`simple`: A verbose logger that presents clear information about the work that Wireit is doing.\u003c/li\u003e\u003cli\u003e`metrics`: Like `simple`, but also presents a summary table of results once a command is finished.\u003c/li\u003e\u003c/ul\u003e |\n| `WIREIT_DEBUG_LOG_FILE` | Path to a file which will receive detailed event logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| `WIREIT_MAX_OPEN_FILES` | Limits the number of file descriptors Wireit will have open concurrently. Prevents resource exhaustion when checking large numbers of cached files. Set to a lower number if you hit file descriptor limits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `WIREIT_PARALLEL`       | [Maximum number of scripts to run at one time](#parallelism).\u003cbr\u003e\u003cbr\u003eDefaults to 2×logical CPU cores.\u003cbr\u003e\u003cbr\u003eMust be a positive integer or `infinity`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `WIREIT_WATCH_STRATEGY` | How Wireit determines when a file has changed which warrants a new watch iteration.\u003cbr\u003e\u003cbr\u003eOptions:\u003cbr\u003e\u003cul\u003e\u003cli\u003e`event` (default): Register OS file system watcher callbacks (using [chokidar](https://github.com/paulmillr/chokidar)).\u003c/li\u003e\u003cli\u003e`poll`: Poll the filesystem every `WIREIT_WATCH_POLL_MS` milliseconds. Less responsive and worse performance than `event`, but a good fallback for when `event` does not work well or at all (e.g. filesystems that don't support filesystem events, or performance and memory problems with large file trees).\u003c/li\u003e\u003c/ul\u003e                                                                                                                  |\n| `WIREIT_WATCH_POLL_MS`  | When `WIREIT_WATCH_STRATEGY` is `poll`, how many milliseconds to wait between each filesystem poll. Defaults to `500`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| `CI`                    | Affects the default value of `WIREIT_CACHE`.\u003cbr\u003e\u003cbr\u003eAutomatically set to `true` by [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables) and most other CI (continuous integration) services.\u003cbr\u003e\u003cbr\u003eMust be exactly `true`. If unset or any other value, interpreted as `false`.                                                                                                                                                                                                                                                                                                                                 |\n\n### Glob patterns\n\nThe following glob syntaxes are supported in the `files` and `output` arrays:\n\n| Example         | Description                                                                              |\n| --------------- | ---------------------------------------------------------------------------------------- |\n| `foo`           | The file named `foo`, or if `foo` is a directory, all recursive children of `foo`.       |\n| `foo/*.js`      | All files directly in the `foo/` directory which end in `.js`.                           |\n| `foo/**/*.js`   | All files in the `foo/` directory, and all recursive subdirectories, which end in `.js`. |\n| `foo.{html,js}` | Files named `foo.html` or `foo.js`.                                                      |\n| `!foo`          | Exclude the file or directory `foo` from previous matches.                               |\n\nAlso note these details:\n\n- Paths should always use `/` (forward-slash) delimiters, even on Windows.\n- Paths are interpreted relative to the current package even if there is a\n  leading `/` (e.g. `/foo` is the same as `foo`).\n- Whenever a directory is matched, all recursive children of that directory are\n  included.\n- `files` are allowed to reach outside of the current package using e.g.\n  `../foo`. `output` files cannot reference files outside of the current\n  package.\n- Symlinks in input `files` are followed, so that they are identified by their content.\n- Symlinks in `output` files are cached as symlinks, so that restoring from\n  cache doesn't create unnecessary copies.\n- The order of `!exclude` patterns is significant.\n- Hidden/dot files are matched by `*` and `**`.\n- Patterns are case-sensitive (if supported by the filesystem).\n\n### Fingerprint\n\nThe following inputs determine the _fingerprint_ for a script. This value is\nused to determine whether a script can be skipped for [incremental\nbuild](#incremental-build), and whether its output can be [restored from\ncache](#caching).\n\n- The `command` setting.\n- The [extra arguments](#extra-arguments) set on the command-line.\n- The `clean` setting.\n- The `output` glob patterns.\n- The SHA256 content hashes of all files matching `files`.\n- The SHA256 content hashes of all files matching `packageLocks` in the current\n  package and all parent directories.\n- The environment variable values configured in `env`.\n- The system platform (e.g. `linux`, `win32`).\n- The system CPU architecture (e.g. `x64`).\n- The system Node version (e.g. `20.11.1`).\n- The fingerprint of all transitive dependencies, unless `cascade` is set to\n  `false`.\n\nWhen using [GitHub Actions caching](#github-actions-caching), the following\ninput also affects the fingerprint:\n\n- The `ImageOS` environment variable (e.g. `ubuntu20`, `macos11`).\n\n## Requirements\n\nWireit is supported on Linux, macOS, and Windows.\n\nWireit is supported on Node Current (22), Active LTS (20), and Maintenance LTS\n(18). See [Node releases](https://nodejs.org/en/about/releases/) for the\nschedule.\n\nWireit scripts can be launched via `npm`, `node --run`, `pnpm`, and `yarn`.\n\n## Related tools\n\nWireit shares a number of features with these other great tools, and we highly\nrecommend you check them out too:\n\n- [Nx](https://nx.dev/)\n- [Turborepo](https://turborepo.org/)\n- [Chomp](https://chompbuild.com/)\n- [Bazel](https://bazel.build/)\n\nHere are some things you might especially like about Wireit:\n\n- **Feels like npm**. When you use Wireit, you'll continue typing the same npm\n  commands you already use, like `npm run build` and `npm test`. There are no\n  new command-line tools to learn, and there's only one way to run each script.\n  Your script config stays in your `package.json`, too. Wireit is designed to be\n  the minimal addition to npm needed to get script dependencies and incremental\n  build.\n\n- **Caching with GitHub Actions**. Wireit supports caching build artifacts and\n  test results directly through GitHub Actions, without any extra third-party\n  services. Just add a single `uses:` line to your workflows.\n\n- **Watch any script**. Want to automatically re-run your build and tests\n  whenever you make a change? Type `npm test --watch`. Any script you've\n  configured using Wireit can be watched by typing `--watch` after it.\n\n- **Great for single packages and monorepos**. Wireit has no opinion about how\n  your packages are arranged. It works great with single packages, because you\n  can link together scripts within the same package. It also works great with\n  any kind of monorepo, because you can link together scripts across different\n  packages using relative paths.\n\n- **Complements npm workspaces**. We think Wireit could be the missing tool that\n  unlocks the potential for [npm\n  workspaces](https://docs.npmjs.com/cli/v8/using-npm/workspaces) to become the\n  best way to set up monorepos. To use Wireit with npm workspaces, you'll just\n  use standard npm workspace commands like `npm run build -ws`.\n\n- **Adopt incrementally**. Wireit scripts can depend on plain npm scripts, so\n  they can be freely mixed. This means you can use Wireit only for the parts of\n  your build that need it most, or you can try it out on a script-by-script\n  basis without changing too much at the same time.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md)\n","funding_links":[],"categories":["TypeScript","Packages","Utilities"],"sub_categories":["Project Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fwireit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fwireit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fwireit/lists"}