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

顔立ち

• 🙂既に知っているコマンドを使用する

  npm run

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

アルファ

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

内容

• 顔立ち
• 取り付ける
• セットアップ
• VSCode Extension
• 依存 関係
  • バニラスクリプト
  • パッケージ間の依存関係
• 平行
• 入力ファイルと出力ファイル
• 増分ビルド
• キャッシング
  • ローカル・キャッシング
  • GitHub アクションのキャッシュ
• クリーニング出力
• ウォッチモード
• パッケージロック
• レシピ
  • タイプスクリプト
• 参考
  • 構成
  • 依存関係の構文
  • 環境変数
  • グロブパターン
  • キャッシュキー
• 必要条件
• 関連ツール
• 貢献

取り付ける

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:

files

output

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

stderr

To enable incremental build, configure the input files for each script by specifying glob patterns in the

wireit.<script>.files

ℹ️ 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

stderr

To enable caching for a script, ensure you have defined both the

files

output

ℹ️ 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

.wireit

Local caching is enabled by default, unless the

CI=true

WIREIT_CACHE=local

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

ℹ️ 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

npm run

npm test

- 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

wireit.<script>.clean

true

"if-file-deleted"

tsc --build

false

Watch mode

In watch mode, Wireit monitors all

files

files

files

watch

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

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

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

[]

Recipes

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

TypeScript

Use incremental build

Set

"incremental": true

tsconfig.json

--build

-b

tsc

Use clean if-file-deleted

The

"clean": "if-file-deleted"

.ts

.ts

"clean": true

.tsbuildinfo

.tsbuildinfo

output

"clean": false

.ts

tsc

.js

Include .tsbuildinfo in output.

Include your

.tsbuildinfo

output

.tsbuildinfo

tsc

Include tsconfig.json in files.

Include your

tsconfig.json

files

Use the --pretty flag

By default,

tsc

stdout

stderr

--pretty

tsc

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>

package.json

command

string

undefined

dependencies

string[]

undefined

files

string[]

undefined

output

string[]

undefined

clean

boolean | "if-file-deleted"

true

packageLocks

string[]

['package-lock.json']

Dependency syntax

The following syntaxes can be used in the

wireit.<script>.dependencies

foo

"foo"

../foo:bar

"bar"

../foo

Environment variables

The following environment variables affect the behavior of Wireit:

WIREIT_PARALLEL

infinity

WIREIT_CACHE

local

CI

true

none

github

google/[email protected]/v1

CI

WIREIT_CACHE

true

true

false

Glob patterns

The following glob syntaxes are supported in the

files

output

foo

foo

foo

foo

foo/*.js

foo/

.js

foo/**/*.js

foo/

.js

foo.{html,js}

foo.html

foo.js

!foo

foo

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:

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

Contributing

See CONTRIBUTING.md