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`

const 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`,
])

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

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

Install

npm install zx

Complete installation instructions: zx/setup

Documentation

Read documentation on google.github.io/zx.

License

Apache-2.0

Disclaimer: This is not an officially supported Google product.