zx

What is zx?

The zx package is a tool for writing better scripts in a Node.js environment. It provides a more convenient and modern way to write shell scripts using JavaScript, leveraging the power of Node.js and its ecosystem.

What are zx's main functionalities?

Running Shell Commands

This feature allows you to run shell commands directly from your JavaScript code using template literals. The `$` function is used to execute the command and handle the output.

const { $ } = require('zx');

(async () => {
  await $`echo Hello, world!`;
})();

Handling Promises

zx makes it easy to handle promises and errors when running shell commands. You can use async/await syntax to manage asynchronous operations and catch errors using try/catch blocks.

const { $ } = require('zx');

(async () => {
  try {
    await $`exit 1`;
  } catch (error) {
    console.error('Command failed:', error);
  }
})();

Using Environment Variables

You can set and use environment variables within your scripts. This is useful for configuring your script's behavior based on different environments or settings.

const { $ } = require('zx');

(async () => {
  process.env.MY_VAR = 'Hello, world!';
  await $`echo $MY_VAR`;
})();

File System Operations

zx provides convenient access to Node.js's fs module, allowing you to perform file system operations like reading and writing files with ease.

const { fs } = require('zx');

(async () => {
  await fs.writeFile('example.txt', 'Hello, world!');
  const content = await fs.readFile('example.txt', 'utf8');
  console.log(content);
})();

Other packages similar to zx

shelljs

ShellJS is a portable (Windows/Linux/macOS) implementation of Unix shell commands on top of the Node.js API. It provides a similar functionality to zx but uses a more traditional approach with a focus on compatibility with Unix shell commands.

execa

Execa is a modern process execution library for Node.js. It provides a more powerful and flexible way to run shell commands compared to zx, with features like better error handling, streaming, and more detailed output.

child_process

The child_process module is a built-in Node.js module that provides the ability to spawn child processes. While it is more low-level and less convenient than zx, it offers more control and flexibility for advanced use cases.

README

🐚 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

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

When using zx via the executable or a shebang, all of the functions ($, cd, fetch, etc) are available straight away without any imports.

$`command`

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

let count = parseInt(await $`ls -1 | wc -l`)
console.log(`Files count: ${count}`)

For example, to upload files in parallel:

let hosts = [...]
await Promise.all(hosts.map(host =>
  $`rsync -azP ./src ${host}:/var/www`  
))

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
  pipe(dest): ProcessPromise<T>
}

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

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

Read more about pipelines.

ProcessOutput

class ProcessOutput {
  readonly exitCode: number
  readonly stdout: string
  readonly stderr: string
  toString(): string
}

cd()

Changes the current working directory.

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

fetch()

A wrapper around the node-fetch package.

let resp = await fetch('http://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.

function sleep(ms: number): Promise<void>

Usage:

await sleep(1000)

chalk package

The chalk package is available without importing inside scripts.

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

fs package

The fs package is available without importing inside scripts. It is asynchronous by default.

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

os package

The os package is available without importing inside scripts.

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

$.shell

Specifies what shell is used. Default is which bash.

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

$.prefix

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

Default is set -euo pipefail;.

$.quote

Specifies a function for escaping special characters during command substitution.

Default is the shq package.

$.verbose

Specifies verbosity. Default is true.

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

__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')

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 (examples/index.md):

zx examples/index.md

Executing remote scripts

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

zx https://medv.io/example-script.mjs

License

Apache-2.0

Disclaimer: This is not an officially supported Google product.