zx@lite: minimalistic shell scripting with TS/JS superpowers

Ditch clunky bash syntax. Script smarter — with fewer dependencies and full TypeScript support.

⚡ What is zx@lite?

The original zx makes shell automations delightful in modern JS runtimes. The @lite version, introduced in v8.5.0, gives you optimal performance, devX without the extra API bloat:

• ✅ Core zx functionality ($, cd, ps)
• ✅ First-class TypeScript support
• ⚡ ~7× smaller than full zx (~124 KB vs ~875 kB)
• 🧱 Static build with zero dependencies.
• 🔌 Wide compat range: Node.js 12+, Deno 1.30+, Bun 1.0+, GraalVM 17+ on Win, Mac or Linux

Ideal for:

• Fast script prototyping
• DevOps and CI automations
• Docker images
• Small CLI tooling

🧾 Setup

npm install zx@lite

TypeScript is an option but highly recommended for safety and better IDE support.

npm install -D typescript @types/node

Attach tsconfig.json like this:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "nodenext",
    "strict": true
  }
}

🧪 Examples

Let’s say you want to clone several repos and list their directories. In bash, this would be a mess of &, wait, and error handling. In zx@lite, it’s much cleaner:

#!/usr/bin/env zx
import { $ } from 'zx'

// Run 3 commands in parallel
await Promise.all([
  $`git clone https://github.com/google/zx zx-clone`,
  $`git clone https://github.com/webpod/webpod webpod-clone`
])

const output = await $`ls -1`
console.log('Cloned directories:\n', output.lines())

• Native parallelism with Promise.all()
• Clean output handling via stdout, lines(), json() helpers
• Controlled error flow: configurable exception throwing behavior

Combine zx@lite with runtime features. Need transport? Just bring in native fetch:

#!/usr/bin/env zx
import { $ } from 'zx'

const repo = 'google/zx'
const latest = await (await fetch(`https://api.github.com/repos/${repo}/releases/latest`)).json()
const v = latest.tag_name
const zip_file = `${repo.replace('/', '-')}-${v}.zip`

await $`curl -o ${zip_file} -L ${latest.zipball_url}`
await $`mkdir -p releases/${v}`
await $`unzip ${zip_file} -d releases/${v}`

console.log('✅ Done')

⚠️ What’s missing in zx@lite?

Check the full API comparison for details.

📦 Upgrade path

Switching between lite and full is trivial:

# Go full speed:
npm install zx

# Back to lean mode:
npm install zx@lite

📚 References

• Documentation
• Sources
• Real world use cases
• Zurk prototype

🧠 Final thoughts

zx@lite is everything you need — and nothing you don’t — for modern scripting with real programming ergonomics. Stop writing fragile bash. Start scripting like a developer.

💬 Got ideas, snippets, or zx@lite tips? Drop them below or feel free to share in the project repo: discussions, issues.