zx: template tags that escape shell arguments, four entry points, and a Google disclaimer

zx exists because child_process is a poor default for a JavaScript script

The README states the problem in three moves. Bash is great, but when a script grows complex many people prefer a more convenient programming language. JavaScript is a perfect choice, but the Node.js standard library requires additional hassle before using it. So the claim is no compromise, take the best of both.

What that means concretely is three things: cross platform wrappers around `child_process`, argument escaping, and sensible defaults. Those three are the product. Everything else in the repository, from the four entry points to the man page, exists to deliver them.

The consequence for a reader is that zx is a convenience layer, not a framework, and its defaults are opinionated in your favour. A script that needs to opt out of the escaping behaviour, to pass a raw shell fragment or to build a command string on purpose, is working against the thing that makes zx worth installing. The README does not describe an escape hatch for that case, so a reader who hits it is left reading the source under `src/` and the documentation site rather than a documented switch.

The template tag is the escaping, and the README example shows why it matters

The whole API in the README is one tag applied to a template literal:

#!/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}`

The last line is the one to read twice. `name` holds the string `foo bar`, with a space in it, and it is interpolated into a path. Because the tag escapes arguments, that value arrives as one argument rather than two, which is the failure the manual string building version of this line produces on a good day. The same mechanism applies to `branch`, which comes out of another command and goes straight back in as `--branch=${branch}`.

The Promise.all block shows the other half of the design: the calls return promises, so concurrency is the language's job rather than a shell ampersand. And every call is awaited, which means a script's failure surfaces as a rejected promise rather than a non zero exit code you have to check for.

The shebang resolves through the zx binary, and the package ships its man page

The first line of the README example is `#!/usr/bin/env zx`, and that line is not decorative. In package.json the `bin` field maps the name `zx` to `build/cli.js`, so the shebang is looking for an executable on your PATH rather than for a file in the repository.

The man page travels with it. The manifest declares `"man": "./man/zx.1"`, and the `files` array ends with `man`, so the page is published in the package. The top-level tree has a `man/` directory to match. That is the detail that makes a global install useful rather than merely possible: after `npm install -g zx` you have both a runner for shebangs and a manual page for the options.

The consequence is a split between using zx from a project and running zx scripts directly. Inside a project, the tagged template is imported as a module and nothing depends on the binary. A script you want to run as `./deploy` depends entirely on the global install being present and on PATH, which is the difference between a script that works on your laptop and one that works in CI where nobody installed anything.

main and exports name different files, and TypeScript resolves through a fourth map

The manifest is `"type": "module"` with `"main": "./build/index.cjs"`, and then the `exports` field publishes four entry points, `.`, `./globals`, `./cli` and `./core`. Each one carries four keys: `types`, `import`, `require` and `default`. So a modern resolver asking for `zx` gets the ESM file while a legacy one following `main` gets the CommonJS build, and both are shipped in the same package.

TypeScript is handled separately again. `typesVersions` maps the same four names to declaration files under `build/`, and `types` points at `./build/index.d.ts` as the default. The consequence is that the module you get depends on which resolver asks, and a deep import such as `zx/core` has to be present in both the `exports` map and the `typesVersions` map or one of the two toolchains in your project will fail on a path that works for the other.

The size of that surface is also the reason the build is not a single command. `build:js` runs a script with a `--format=cjs --hybrid` flag and an entry glob covering `src/{cli,core,deps,glo...}`, which is how one source tree becomes the pairs of `.js` and `.cjs` files the export map promises.

Node 12.17 is the floor, and PowerShell counts as a supported shell

The `engines` field requires Node `>= 12.17.0`, and the compatibility list names Node.js at that floor, Bun `>= 1.0.0`, Deno 1.x and 2.x, and GraalVM Node.js, across Linux, macOS and Windows. Modules can be CommonJS or ESM, written in JavaScript or TypeScript, and the shell is Bash or PowerShell.

Two things follow from that list. The runtime floor is far below the version most people have installed, so the package is expected to run on a much older Node than the examples in the documentation imply, which is a constraint on what the source can use rather than an invitation to run old runtimes. And naming PowerShell as a supported shell means the same script is expected to work where the default shell is not the one you write in.

The consequence is that argument escaping, which is the main reason to use zx, has to behave correctly in both shells, and a reader who moves a script from a Linux box to a Windows one is relying on that rather than on the argument being a plain string. The documentation links shell specifics to its own page, so the details live off the repository. If your scripts are Bash only and will stay that way, the Windows entry is one you can ignore, and if they are not, that page is the thing to read first.

package.json says 8.9.0 while the newest published tag is 8.8.5

The version in the checked-in manifest and the newest release are not the same thing. `package.json` declares 8.9.0. The release list shows 8.8.5, released 2025-10-19, 8.8.4 from 2025-09-26 and 8.8.3 from 2025-09-20, and the GitHub release titles carry mechanical codenames alongside the numbers, Temporary Reservoir, Flange Coupling and Sealing Gasket. The last push to the default branch, main, was on 2026-08-14.

The consequence is that main carries work that no user has installed. If you clone the repository and reproduce a bug, you are reproducing something in 8.9.0, and any answer you file or read may be about 8.8.5. A bug report that names only the branch is therefore ambiguous, which is why the numbered tag is the thing to quote in an issue.

The build reinforces the split. `prebuild` removes `build` outright with `rm -rf build`, and `build` runs `build:versions`, then `build:js`, then `build:dts`, then `build:tests`, so a version step runs before anything is emitted. For a reader, the practical takeaway is small: install a published version with npm, and only build from source if you intend to change something.

The examples directory is the documentation, and the seven files are the feature list

The README's usage section is two links, the documentation site and the examples directory, and the examples directory is the more informative of the two because its filenames are a map of what the library is for. There are seven: `hello.mjs`, `parallel.mjs`, `interactive.mjs`, `background-process.mjs`, `fetch-weather.mjs`, `backup-github.mjs` and `npm-oidc-enable.mjs`.

Read as a set, they cover the four things a script runner has to get right. Fetching, with the weather and GitHub backup examples. Concurrency, in `parallel.mjs`, which is the expanded form of the Promise.all block in the README. Processes that outlive the script, in `background-process.mjs`, and processes that talk to the user, in `interactive.mjs`. And credentials, in `npm-oidc-enable.mjs`, which is a file whose name says the sensitive part.

The consequence is a practical way to evaluate the project: instead of reading prose, read those seven files and see whether the shape of the code you would write matches. The `docs/` directory in the tree is where the prose lives, and the See also section points at zx@lite for a lighter build and at MAML for JSON config files with comments, multiline strings, unquoted keys and optional commas.

The package says it is not an officially supported Google product

One line at the bottom of the README is a disclaimer and it is the one line that matters to anyone choosing a dependency: this is not an officially supported Google product. The package is Apache-2.0 licensed, the repository is `google/zx`, and the documentation is hosted at google.github.io, which is a GitHub Pages address rather than a google.com one.

The consequence is about expectations rather than code. There is no Google support contract behind this package, so the community is the route for problems, and the compatibility list, the four entry points and the escaping behaviour are things the project maintains rather than something a large company has committed to preserving. The See also links make the same point in a smaller way, pointing to zx@lite and to MAML rather than to internal Google tooling.

For a reader evaluating zx, that is a reasonable trade for a package whose argument for existing is stated in four sentences, provided nobody on the team believes they are getting an internal library. The tree around it suggests an ordinary open source project with ordinary checks: a `.commitlintrc`, a `lefthook.yml` for hooks, a `.nycrc` for coverage, a `.size-limit.json` for bundle size, a `tsconfig.json`, a `test/` and a `test-d/` directory for type tests, and a `zizmor.yml` for workflow scanning.

Editorial conclusion

zx fits a team whose scripts have outgrown shell but do not justify a whole CLI framework, and who want argument escaping and sensible defaults without configuring them. It is a poor fit if you need a maintained Google product behind it, since the project states plainly that it is not an officially supported Google product, and a poor fit if your tooling assumes a single module format, because the package publishes both ESM and CJS. Before adopting it, read the four entry points in package.json rather than importing the root and assuming, and pin a published version: the checked-in manifest says 8.9.0 while the newest tag is 8.8.5 from October 2025.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes