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.
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 '@cspotcode/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.
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.
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 '@cspotcode/zx/experimental'let {stdout} = await retry(5)`curl localhost`// with a specified delay between attemptslet {stdout} = await retry(3, 500)`npm whoami`
echo()
A console.log() alternative which can take ProcessOutput.
import {echo} from '@cspotcode/zx/experimental'let branch = await $`git branch --show-current`echo`Current branch is ${branch}.`// orecho('Current branch is', branch)
startSpinner()
Starts a simple CLI spinner, and returns stop() function.
import {startSpinner} from '@cspotcode/zx/experimental'let stop = startSpinner()await $`long-running command`stop()
withTimeout()
Runs and sets a timeout for a cmd.
import {withTimeout} from '@cspotcode/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 nodeimport {$} from '@cspotcode/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 '@cspotcode/zx'// Or import '@cspotcode/zx/globals'void async function () { await $`ls -la`}()
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.