wireit - Wireitはnpmスクリプトをアップグレードして、よりスマートで効率的なものにします。

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

Created at: 2021-12-22 23:52:53
Language: TypeScript
License: Apache-2.0

ワイヤート

Wireitはnpmスクリプトをアップグレードして、よりスマートで効率的なものにします。

で公開 npm ビルドステータス

顔立ち

  • 🙂既に知っているコマンドを使用する
    npm run
  • ⛓️npmスクリプト間の依存関係を並列に自動的に実行する
  • 👀スクリプトを監視し、変更時に継続的に再実行する
  • 🥬既に新しいスクリプトをスキップする
  • ♻️出力をローカルおよびリモートでGitHubアクションに無料でキャッシュする
  • 🛠️単一のパッケージ、npmワークスペース、およびその他のモノレポで動作します

アルファ

🚧Wireitはアルファソフトウェアであり、活発だが初期の開発段階にある。あなたはそれを試してみることを歓迎しますが、あなたが遭遇するかもしれない多くの欠けている機能や問題があることに注意してください!🚧

内容

取り付ける

npm i -D wireit

セットアップ

Wireitは、 動作しますが、それを置き換えません。Wireit の NPM スクリプトを設定するには、コマンドを の新しいセクションに移動し、元のスクリプトをコマンドに置き換えます。

npm run
wireit
package.json
wireit

以前は
{
  "scripts": {
    "build": "tsc"
  }
}
{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    }
  }
}

実行すると、Wireitはスクリプトをよりスマートで効率的にアップグレードします。Wireitはpnpmでも動作します。

npm run build

また、ファイルに追加する必要があります。Wireitはディレクトリを使用して、スクリプトのキャッシュやその他のデータを格納します。

.wireit
.gitignore
.wireit

echo .wireit >> .gitignore

VSCode Extension

VSCode を使用する場合は、拡張機能のインストールを検討してください。ホバー、オートコンプリートに関するドキュメントを追加し、多くの一般的な間違いを診断できます。

google.wireit

マーケットプレイスから、またはコマンドラインに次のようにインストールします。

code --install-extension google.wireit

依存 関係

2 つのスクリプト間の依存関係を宣言するには、リストを編集します。

wireit.<script>.dependencies

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

実行すると、スクリプトが自動的に最初に実行されます。

npm run bundle
build

バニラスクリプト

依存するスクリプトはWireit用に設定する必要はなく、バニラスクリプトにすることができます。これにより、一部のスクリプトに対してのみWireitを使用したり、段階的にアップグレードしたりできます。Wireit 用に設定されていないスクリプトは、依存関係として常に安全に使用できます。彼らは完全に最適化されません。

npm

パッケージ間の依存関係

依存関係は、構文 で相対パスを使用して、他の npm パッケージ内のスクリプトを参照できます。すべてのパッケージ間の依存関係は、 で始まる必要があります。クロスパッケージの依存関係は、npmワークスペースや他の種類のモノリポジトリでうまく機能します。

<relative-path>:<script-name>
"."

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

平行

Wireitは、依存関係グラフに従ってスクリプトを並列に実行しても安全です。

たとえば、この図では、スクリプトとスクリプトは並列に実行されますが、スクリプトは両方が開始されて終了するまで開始されません。

B
C
A
B
C

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

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
files
Requires
output
Dependency graph - -
Incremental build ☑️ -
Watch mode ☑️ -
Clean 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"]
    }
  }
}

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. 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: []
).

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. 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.

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/[email protected]/v1

Example workflow

# File: .github/workflows/tests.yml

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

      # Set up GitHub Actions caching for Wireit.
      - uses: google/[email protected]/v1

      # 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:

Setting Description
true
Clean before every run (the default).
"if-file-deleted"
Clean only if an input file has been deleted since the last run.

Use 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 for more on this example.)
false
Do not clean.

Only use this option if you are certain that the script command itself already takes care of removing outdated files from previous runs.

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, 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.

Package locks

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:

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
[]
.

Recipes

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

TypeScript

Use incremental build

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.

Use clean if-file-deleted

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 .tsbuildinfo in output.

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 tsconfig.json in files.

Include your

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

Use the --pretty flag

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.

Example

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

Reference

Configuration

The following properties can be set inside

wireit.<script>
objects in
package.json
files:

Property Type Default Description
command
string
undefined
The shell command to run.
dependencies
string[]
undefined
Scripts that must run before this one.
files
string[]
undefined
Input file glob patterns, used to determine the cache key.
output
string[]
undefined
Output file glob patterns, used for caching and cleaning.
clean
boolean | "if-file-deleted"
true
Delete output files before running.
packageLocks
string[]
['package-lock.json']
Names of package lock files.

Dependency syntax

The following syntaxes can be used in the

wireit.<script>.dependencies
array:

Example Description
foo
Script named
"foo"
in the same package.
../foo:bar
Script named
"bar"
in the package found at
../foo
(details).

Environment variables

The following environment variables affect the behavior of Wireit:

Variable Description
WIREIT_PARALLEL
Maximum number of scripts to run at one time.

Defaults to 4×CPUs.

Must be a positive integer or
infinity
.
WIREIT_CACHE
Caching mode.

Defaults to
local
unless
CI
is
true
, in which case defaults to
none
.

Automatically set to
github
by the
google/[email protected]/v1
action.

Options:
  • local
    : Cache to local disk.
  • github
    : Cache to GitHub Actions.
  • none
    : Disable caching.
CI
Affects the default value of
WIREIT_CACHE
.

Automatically set to
true
by GitHub Actions and most other CI (continuous integration) services.

Must be exactly
true
. If unset or any other value, interpreted as
false
.

Glob patterns

The following glob syntaxes are supported in the

files
and
output
arrays:

Example Description
foo
The file named
foo
, or if
foo
is a directory, all recursive children of
foo
.
foo/*.js
All files directly in the
foo/
directory which end in
.js
.
foo/**/*.js
All files in the
foo/
directory, and all recursive subdirectories, which end in
.js
.
foo.{html,js}
Files named
foo.html
or
foo.js
.
!foo
Exclude the file or directory
foo
from previous matches.

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).

Cache key

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
    ).

Requirements

Wireit is supported on Linux, macOS, and Windows.

Wireit is supported on Node Current (18), Active LTS (16), and the most recent Maintenance LTS (14). See Node releases for the schedule.

Related tools

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

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.

Contributing

See CONTRIBUTING.md