buffuwei / zx

A tool for writing better scripts

🐚 zx

#!/usr/bin/env zx

await $`cat package.json | grep name`

let branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`

await Promise.all([
  $`sleep 1; echo 1`,
  $`sleep 2; echo 2`,
  $`sleep 3; echo 3`,
])

let name = 'foo bar'
await $`mkdir /tmp/${name}`

Bash is great, but when it comes to writing scripts, people usually choose a more convenient programming language. JavaScript is a perfect choice, but standard Node.js library requires additional hassle before using. The zx package provides useful wrappers around child_process, escapes arguments and gives sensible defaults.

Install

npm i -g zx

Requirement: Node version >= 16.0.0

Goods

$ · cd() · fetch() · question() · sleep() · nothrow() · quiet() · within() · chalk · fs · os · path · globby · yaml · minimist · which · __filename · __dirname · require()

Documentation

Write your scripts in a file with .mjs extension in order to be able to use await on top level. If you prefer the .js extension, wrap your scripts in something like void async function () {...}().

Add the following shebang to the beginning of your zx scripts:

#!/usr/bin/env zx

Now you will be able to run your script like so:

chmod +x ./script.mjs
./script.mjs

Or via the zx executable:

zx ./script.mjs

All functions ($, cd, fetch, etc) are available straight away without any imports.

Or import globals explicitly (for better autocomplete in VS Code).

import 'zx/globals'

$`command`

Executes a given string using the spawn function from the child_process package and returns ProcessPromise<ProcessOutput>.

Everything passed through ${...} will be automatically escaped and quoted.

let name = 'foo & bar'
await $`mkdir ${name}`

There is no need to add extra quotes. Read more about it in quotes.

You can pass an array of arguments if needed:

let flags = [
  '--oneline',
  '--decorate',
  '--color',
]
await $`git log ${flags}`

If the executed program returns a non-zero exit code, ProcessOutput will be thrown.

try {
  await $`exit 1`
} catch (p) {
  console.log(`Exit code: ${p.exitCode}`)
  console.log(`Error: ${p.stderr}`)
}

ProcessPromise

class ProcessPromise<T> extends Promise<T> {
  readonly stdin: Writable
  readonly stdout: Readable
  readonly stderr: Readable
  readonly exitCode: Promise<number>
  pipe(dest): ProcessPromise<T>
  kill(signal = 'SIGTERM'): Promise<void>
}

The pipe() method can be used to redirect stdout:

await $`cat file.txt`.pipe(process.stdout)

Read more about pipelines.

ProcessOutput

class ProcessOutput {
  readonly stdout: string
  readonly stderr: string
  readonly exitCode: number
  readonly signal: 'SIGTERM' | 'SIGKILL' | ...
  toString(): string
}

Functions

cd()

Changes the current working directory.

cd('/tmp')
await $`pwd` // outputs /tmp

fetch()

A wrapper around the node-fetch package.

let resp = await fetch('https://wttr.in')
if (resp.ok) {
  console.log(await resp.text())
}

question()

A wrapper around the readline package.

Usage:

let bear = await question('What kind of bear is best? ')
let token = await question('Choose env variable: ', {
  choices: Object.keys(process.env)
})

In second argument, array of choices for Tab autocompletion can be specified.

function question(query?: string, options?: QuestionOptions): Promise<string>
type QuestionOptions = { choices: string[] }

sleep()

A wrapper around the setTimeout function.

await sleep(1000)

nothrow()

Changes behavior of $ to not throw an exception on non-zero exit codes.

function nothrow<P>(p: P): P

Usage:

await nothrow($`grep something from-file`)

// Inside a pipe():

await $`find ./examples -type f -print0`
  .pipe(nothrow($`xargs -0 grep something`))
  .pipe($`wc -l`)

If only the exitCode is needed, you can use the next code instead:

if (await $`[[ -d path ]]`.exitCode == 0) {
  ...
}

// Equivalent of:

if ((await nothrow($`[[ -d path ]]`)).exitCode == 0) {
  ...
}

quiet()

Changes behavior of $ to disable verbose output.

function quiet<P>(p: P): P

Usage:

await quiet($`grep something from-file`)
// Command and output will not be displayed.

within()

Creates a new async context.

function within(callback): void

Usage:

$.verbose = true
await $`pwd` // => /home/path

within(async () => {
  $.verbose = false
  cd('/tmp')
  
  setTimeout(async () => {
    await $`pwd` // => /tmp
    assert($.verbose == false)
  }, 1000)
})

await $`pwd` // => /home/path
assert($.verbose == true)

Packages

Following packages are available without importing inside scripts.

chalk package

The chalk package.

console.log(chalk.blue('Hello world!'))

fs package

The fs-extra package.

let content = await fs.readFile('./package.json')

os package

The os package.

await $`cd ${os.homedir()} && mkdir example`

path package

The path package.

await $`mkdir ${path.join(basedir, 'output')}`

globby package

The globby package.

let packages = await globby(['package.json', 'packages/*/package.json'])

let pictures = globby.globbySync('content/*.(jpg|png)')

Also, globby available via the glob shortcut:

await $`svgo ${await glob('*.svg')}`

yaml package

The yaml package.

console.log(YAML.parse('foo: bar').foo)

minimist package

The minimist package.

Available as global const argv.

which package

The which package.

let node = await which('node')

let node = which.sync('node')

Configuration

$.shell

Specifies what shell is used. Default is which bash.

$.shell = '/usr/bin/bash'

Or use a CLI argument: --shell=/bin/bash

$.spawn

Specifies a spawn api. Defaults to require('child_process').spawn.

$.maxBuffer

Specifies the largest number of bytes allowed on stdout or stderr. Defaults to 200 * 1024 * 1024 (200 MiB).

$.prefix

Specifies the command that will be prefixed to all commands run.

Default is set -euo pipefail;.

Or use a CLI argument: --prefix='set -e;'

$.quote

Specifies a function for escaping special characters during command substitution.

$.verbose

Specifies verbosity. Default is true.

In verbose mode, the zx prints all executed commands alongside with their outputs.

Or use a CLI argument --quiet to set $.verbose = false.

$.env

Specifies env map. Defaults to process.env.

Polyfills

__filename & __dirname

In ESM modules, Node.js does not provide __filename and __dirname globals. As such globals are really handy in scripts, zx provides these for use in .mjs files (when using the zx executable).

require()

In ESM modules, the require() function is not defined. The zx provides require() function, so it can be used with imports in .mjs files (when using zx executable).

let {version} = require('./package.json')

Experimental

The zx also provides a few experimental functions. Please leave a feedback about those features in the discussion. To enable new features via CLI pass --experimental flag.

retry()

Retries a command a few times. Will return after the first successful attempt, or will throw after specifies attempts count.

import {retry} from 'zx/experimental'

let {stdout} = await retry(5)`curl localhost`

// with a specified delay between attempts
let {stdout} = await retry(3, 500)`npm whoami`

echo()

A console.log() alternative which can take ProcessOutput.

import {echo} from 'zx/experimental'

let branch = await $`git branch --show-current`

echo`Current branch is ${branch}.`
// or
echo('Current branch is', branch)

startSpinner()

Starts a simple CLI spinner, and returns stop() function.

import {startSpinner} from 'zx/experimental'

let stop = startSpinner()
await $`long-running command`
stop()

withTimeout()

Runs and sets a timeout for a cmd.

import {withTimeout} from 'zx/experimental'

await withTimeout(100, 'SIGTERM')`sleep 9999`

FAQ

Passing env variables

process.env.FOO = 'bar'
await $`echo $FOO`

Passing array of values

If array of values passed as argument to $, items of the array will be escaped individually and concatenated via space.

Example:

let files = [...]
await $`tar cz ${files}`

Importing from other scripts

It is possible to make use of $ and other functions via explicit imports:

#!/usr/bin/env node
import {$} from 'zx'
await $`date`

Scripts without extensions

If script does not have a file extension (like .git/hooks/pre-commit), zx assumes that it is an ESM module.

Markdown scripts

The zx can execute scripts written in markdown (docs/markdown.md):

zx docs/markdown.md

TypeScript scripts

import {$} from 'zx'
// Or 
import 'zx/globals'

void async function () {
  await $`ls -la`
}()

Use ts-node as a esm node loader.

node --loader ts-node/esm script.ts

You must set "type": "module" in package.json and "module": "ESNext" in tsconfig.json.

{
  "type": "module"
}

{
  "compilerOptions": {
    "module": "ESNext"
  }
}

Executing remote scripts

If the argument to the zx executable starts with https://, the file will be downloaded and executed.

zx https://medv.io/game-of-life.js

Executing scripts from stdin

The zx supports executing scripts from stdin.

zx <<'EOF'
await $`pwd`
EOF

Attaching .bash_profile/.zshrc

By default child_process does not include aliases and bash functions. But you are still able to do it by hand. Just attach necessary directives to $.prefix.

$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
await $`nvm -v`

Using GitHub Actions

Default GitHub Action runner comes with npx installed.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3

    - name: Build
      env:
        FORCE_COLOR: 3
      run: |
        npx zx <<'EOF'
        await $`...`
        EOF

License

Apache-2.0

Disclaimer: This is not an officially supported Google product.