icelamar / wireit Goto Github PK

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

• 🙂 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

🚧 Wireit is alpha software — in active but early development. You are welcome to try it out, but note there a number of missing features and issues that you may run into! 🚧

• Features
• Install
• Setup
• VSCode Extension
• Dependencies
  • Vanilla scripts
  • Cross-package dependencies
• Parallelism
• Input and output files
• Incremental build
• Caching
  • Local caching
  • GitHub Actions caching
• Cleaning output
• Watch mode
• Package locks
• Recipes
  • TypeScript
• Reference
  • Configuration
  • Dependency syntax
  • Environment variables
  • Glob patterns
  • Cache key
• Requirements
• Related tools
• Contributing

npm i -D wireit

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 works with yarn and pnpm, too.

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

If you use VSCode, consider installing the google.wireit extension. It adds documentation on hover, autocomplete, and can diagnose a number of common mistakes.

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

code --install-extension google.wireit

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.

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.

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"]
    }
  }
}

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 4 scripts in parallel for every 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

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:

{
  "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"]
    }
  }
}

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. When a script is skipped, any stdout or stderr that it produced in the previous run is replayed.

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

ℹ️ If a script doesn't have a files 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 files, set files to an empty array (files: []).

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. When a script is restored from cache, any stdout or stderr is replayed.

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.

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.

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/v1

# File: .github/workflows/tests.yml

name: Tests
on: [push, pull_request]
jobs:
  tests:
    os: ubuntu-20.04
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: true

      # Set up GitHub Actions caching for Wireit.
      - uses: google/wireit@setup-github-actions-caching/v1

      # Install npm dependencies.
      - run: npm ci

      # Run tests. Wireit will automatically use
      # the GitHub Actions cache whenever possible.
      - run: npm test

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:

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, ensure that the files array is defined, and add the watch argument:

npm run <script> watch

The benefit of Wireit's watch mode over built-in watch modes are:

• Wireit watches the entire dependency graph, so a single watch command replaces many built-in ones.
• It prevents problems that can occur when running many separate watch commands simultaneously, such as build steps being triggered before all preceding steps have finished.

By default, Wireit automatically treats package-lock.json files in the package directory, plus all parent directories, as input files. This is useful because installing or upgrading your dependencies can affect the behavior of your scripts, so it's important to re-run them whenever your dependencies change.

If you are using an alternative package manager instead of npm, then your package lock files might be named something else. Some examples are:

• Yarn: yarn.lock (configurable)
• pnpm: pnpm-lock.yaml

To change the name of the package lock files Wireit should look for, specify it in the wireit.<script>.packageLocks array. Wireit will look for the given filenames in the script's directory, as well as in all of its parent directories. You can specify multiple filenames here, if needed.

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"],
      "packageLocks": ["yarn.lock"]
    }
  }
}

If you're sure that a script isn't affected by dependencies at all, you can turn off this behavior entirely to improve your cache hit rate by setting wireit.<script>.packageLocks to [].

This section contains advice about integrating specific build tools with Wireit.

Set "incremental": true in your tsconfig.json, and use the --build (or -b) flag in your tsc command. This enables TypeScript's incremental compilation mode, which significantly reduces compile times.

The "clean": "if-file-deleted" setting provides the best balance between fast and correct output, giving you an incremental build when a .ts source file is added or modified, and a clean build when a .ts source file is deleted.

"clean": true (the default) is not a good option, because it either eliminates the benefits of incremental compilation, or causes your .tsbuildinfo to get out of sync, depending on whether you include your .tsbuildinfo file in the output array.

"clean": false is also not a good option, because it causes stale outputs to accumulate. This is because when you delete or rename a .ts source file, tsc itself does not automatically delete the corresponding .js file emitted by previous compiles.

Include your .tsbuildinfo file in your output array. Otherwise, when Wireit performs a clean build, the .tsbuildinfo file will get out-of-sync with the output, and tsc will wrongly skip emit because it believes the output is already up-to-date.

Include your tsconfig.json file in your files array so that Wireit knows to re-run when you change a setting that affects compilation.

By default, tsc only shows colorful stylized output when it detects that it is attached to an interactive (TTY) terminal. The processes spawned by Wireit do not perceive themselves to be attached to an interactive terminal, because of the way Wireit captures stdout and stderr for replays. The --pretty flag forces tsc to emit colorful stylized output even on non-interactive terminals.

{
  "scripts": {
    "ts": "wireit"
  },
  "wireit": {
    "ts": {
      "command": "tsc --build --pretty",
      "clean": "if-file-deleted",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**", ".tsbuildinfo"]
    }
  }
}

The following properties can be set inside wireit.<script> objects in package.json files:

The following syntaxes can be used in the wireit.<script>.dependencies array:

The following environment variables affect the behavior of Wireit:

The following glob syntaxes are supported in the files and output arrays:

Also note these details:

• Whenever a directory is matched, all recursive children of that directory are included.
• Symlinks in input files are followed, so that they are identified by their content.
• Symlinks in output files are cached as symlinks, so that restoring from cache doesn't create unnecessary copies.
• The order of !exclude patterns is significant.
• Hidden/dot files are matched by * and **.
• Patterns are case-sensitive (if supported by the filesystem).

The following inputs determine the cache key for a script. This key is used to determine whether a script can be skipped for incremental build, and whether its output can be restored from cache.

• The command setting.
• The clean setting.
• The output glob patterns.
• The SHA256 content hashes of all files matching files.
• The SHA256 content hashes of all files matching packageLocks in the current package and all parent directories.
• The system platform (e.g. linux, win32).
• The system CPU architecture (e.g. x64).
• The system Node version (e.g. 16.7.0).
• The cache key of all transitive dependencies.

When using GitHub Actions caching, the following input also affects the cache key:

• The ImageOS environment variable (e.g. ubuntu20, macos11).

Wireit is supported on Linux, macOS, and Windows.

Wireit requires Node Active LTS (16.7.0+) or Current (18.0.0+). Node Maintenance LTS releases are not supported. See here for Node's release schedule.

Wireit shares a number of features with these other great tools, and we highly recommend you check them out too:

• Nx
• Turborepo
• Chomp
• Bazel

Here are some things you might especially like about Wireit:

• Feels like npm. When you use Wireit, you'll continue typing the same npm commands you already use, like npm run build and npm test. There are no new command-line tools to learn, and there's only one way to run each script. Your script config stays in your package.json, too. Wireit is designed to be the minimal addition to npm needed to get script dependencies and incremental build.

• Caching with GitHub Actions. Wireit supports caching build artifacts and test results directly through GitHub Actions, without any extra third-party services. Just add a single uses: line to your workflows.

• Watch any script. Want to automatically re-run your build and tests whenever you make a change? Type npm test watch. Any script you've configured using Wireit can be watched by typing watch after it.

• Great for single packages and monorepos. Wireit has no opinion about how your packages are arranged. It works great with single packages, because you can link together scripts within the same package. It also works great with any kind of monorepo, because you can link together scripts across different packages using relative paths.

• Complements npm workspaces. We think Wireit could be the missing tool that unlocks the potential for npm workspaces to become the best way to set up monorepos. To use Wireit with npm workspaces, you'll just use standard npm workspace commands like npm run build -ws.

• Adopt incrementally. Wireit scripts can depend on plain npm scripts, so they can be freely mixed. This means you can use Wireit only for the parts of your build that need it most, or you can try it out on a script-by-script basis without changing too much at the same time.

See CONTRIBUTING.md