Que fait Zx — Écrire de meilleurs scripts shell avec JavaScript ?
Vue d'ensemble
zx est l'outil de Google pour écrire des scripts shell en JavaScript/TypeScript. Il encapsule child_process, échappe automatiquement les arguments et fournit des valeurs par défaut judicieuses — vous donnant la puissance de l'écosystème JavaScript dans vos scripts.
#!/usr/bin/env zx
await $`cat package.json | grep name`
const branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`
const name = 'foo & bar'
await $`mkdir /tmp/${name}` // Pas besoin de guillemets — échappement automatique
Bash est excellent pour les tâches simples, mais quand les scripts deviennent complexes, un langage de programmation complet est utile. zx ajoute des wrappers pratiques autour de child_process, échappe les arguments et donne des valeurs par défaut judicieuses. Pensez-y comme : bash + JavaScript dans un seul script.
Déclencheurs
Se déclenche également lorsque les utilisateurs demandent à exécuter des commandes shell en JavaScript, à convertir des scripts bash en zx, à exécuter des scripts distants, des scripts Markdown ou des scripts shell TypeScript.
Démarrage rapide
npm install zx
Écrivez les scripts sous forme de fichiers .mjs (prend en charge le await de niveau supérieur). Ajoutez le shebang #!/usr/bin/env zx ou exécutez via la CLI :
zx ./script.mjs # Exécution directe
npx zx ./script.mjs # Via npx
node --import zx/globals # En tant que loader Node.js
Toutes les fonctions ($, cd, fetch, etc.) sont disponibles globalement dans les scripts zx sans import. Pour des importations explicites (meilleur autocomplétion VS Code) :
import 'zx/globals'
Concepts fondamentaux
$`commande` — Exécuter des commandes shell
Le littéral de gabarit étiqueté est le cœur de zx. Tout ce qui se trouve dans ${...} est automatiquement échappé et entre guillemets.
// Asynchrone (standard) — retourne une ProcessPromise
const output = await $`ls -la`
// Variante synchrone — retourne directement un ProcessOutput
const dir = $.sync`pwd`
// Les tableaux sont aplatis
const flags = ['--oneline', '--decorate', '--color']
await $`git log ${flags}`
// Les codes de sortie non nuls lèvent une exception ProcessOutput
try {
await $`exit 1`
} catch (p) {
console.log(`Sortie : ${p.exitCode}, Erreur : ${p.stderr}`)
}
Configuration présélectionnée avec $({...})
Créez des instances $ personnalisées avec des options prédéfinies — chaînables et composables :
const $$ = $({ verbose: false, env: { NODE_ENV: 'production' } })
const pwd = $$.sync`pwd`
// Les configurations présélectionnées sont chaînables
const $1 = $({ nothrow: true })
const $2 = $1({ sync: true }) // Les deux options nothrow + sync sont appliquées
ProcessPromise et ProcessOutput
$`cmd` ProcessPromise (étend Promise)
├── .pipe() Piping de flux
├── .kill() Terminer le processus
├── .text() Sortie sous forme de chaîne
├── .json() Sortie sous forme de JSON parsé
├── .lines() Sortie divisée en lignes
├── .nothrow() Supprimer les erreurs pour cette commande
├── .quiet() Supprimer la sortie pour cette commande
├── .timeout() Auto-arrêt après une durée
├── .stdio() Configurer les E/S
├── .exitCode Promise<code de sortie>
├── .stdout Flux lisible
├── .stderr Flux lisible
├── .stdin Flux inscriptible
├── .pid / .cmd Métadonnées du processus
└── await → ProcessOutput
├── .stdout string
├── .stderr string
├── .exitCode number
├── .signal string|null
├── .text() / .json() / .lines() / .buffer() / .blob()
└── .ok boolean (quand nothrow est utilisé)
Arbre de décision
Lors de l'écriture de scripts zx, utilisez cet arbre de décision :
| Objectif | Approche |
|---|---|
| Exécuter une commande | await $`cmd` |
| Exécuter de manière synchrone | $.sync`cmd` |
| Rediriger la sortie | .pipe($`suivante`) / .pipe('fichier.txt') |
| Gérer les erreurs avec élégance | $({nothrow: true}) / .nothrow() |
| Définir un délai d'attente | $({timeout: '30s'}) / .timeout('30s') |
| Analyser la sortie JSON | (await $`cmd`).json() |
| Streaming en temps réel | for await (const line of $`cmd`) |
| Réessayer en cas d'échec | retry(5, () => $`cmd`) |
| Invite utilisateur | question('Nom : ') |
| Indicateur de progression | await spinner('Travail en cours...', () => $`cmd`) |
| Changer de répertoire | cd('/chemin') ou within(() => { $.cwd = '/tmp' }) |
| Fichiers/répertoires temporaires | tmpfile() / tmpdir() |
| Analyser les arguments CLI | argv.flag ou minimist(process.argv.slice(2)) |
| Charger un fichier .env | dotenv.config('.env') |
Écrire des scripts zx efficaces
Exécution parallèle
const results = await Promise.all([
$`sleep 1; echo 1`,
$`sleep 2; echo 2`,
$`sleep 3; echo 3`,
])
Gestion des erreurs avec nothrow
$.nothrow = true
const repos = ['zx', 'webpod']
const clones = repos.map(n => $`git clone https://github.com/google/${n}`)
const results = await Promise.all(clones)
const errors = results.filter(o => !o.ok).map(o => o.stderr.trim())
console.log('Erreurs :', errors.join('\n'))
Piping de flux
// Chaîner des commandes comme des pipes bash
const greeting = await $`printf "hello"`
.pipe($`awk '{printf $1", world!"}'`)
.pipe($`tr '[a-z]' '[A-Z]'`)
// Rediriger vers un fichier
await $`echo "Hello!"`.pipe('/tmp/output.txt')
// Sortie en temps réel vers le terminal
await $`echo 1; sleep 1; echo 2; sleep 1; echo 3`.pipe(process.stdout)
Division et fusion de flux
// Diviser une source vers plusieurs consommateurs
const p = $`une-commande`
const [o1, o2] = await Promise.all([
p.pipe`log`,
p.pipe`extraire`,
])
// Fusionner plusieurs sources
const $h = $({ halt: true })
const p1 = $`echo foo`
const p2 = $h`echo a && sleep 0.1 && echo b`
const p3 = $h`echo c && sleep 0.1 && echo d`
const cat = $h`cat`
p1.pipe(cat); p2.pipe(cat); p3.pipe(cat)
await cat.run()
Formateurs de sortie
const p = $`echo '{"foo":"bar"}\nline2'`
await p.json() // { foo: 'bar' }
await p.lines() // ['{"foo":"bar"}', 'line2']
await p.text() // '{"foo":"bar"}\nline2\n'
Itération asynchrone
for await (const line of $`git log --oneline --max-count=5`) {
console.log(line)
}
Configuration du shell
zx utilise bash par défaut. Changez de shell selon vos besoins :
import { useBash, usePowerShell, usePwsh } from 'zx'
usePowerShell() // PowerShell.exe
usePwsh() // PowerShell v7+
useBash() // Retour à bash
// Surcharge manuelle
$.shell = '/bin/zsh'
Sous Windows, envisagez d'utiliser WSL ou Git Bash pour le support bash, ou passez à PowerShell via usePowerShell().
Résumé des helpers intégrés
| Helper | Objectif | Exemple |
|---|---|---|
cd() | Changer de répertoire | cd('/tmp') |
fetch() | Requêtes HTTP, prend en charge .pipe() | fetch('https://api.example.com') |
question() | Saisie utilisateur interactive | question('Nom : ') |
sleep() | Retarder l'exécution | await sleep(1000) |
echo() | Afficher sur stdout | echo`Statut : ${p}` |
stdin() | Lire depuis stdin | JSON.parse(await stdin()) |
within() | Contexte de configuration asynchrone isolé | within(() => { $.cwd = '/tmp' }) |
retry() | Réessayer avec délai/backoff | retry(5, () => $curl url) |
spinner() | Indicateur de progression CLI | await spinner(() => $longue-commande) |
glob() | Correspondance de fichiers glob (globby) | glob('**/*.js') |
which() | Trouver le chemin d'un exécutable | await which('node') |
ps | Liste des processus multiplateforme | ps.lookup({ command: 'node' }) |
tmpdir() | Répertoire temporaire | tmpdir('sous') |
tmpfile() | Fichier temporaire | tmpfile('f.txt', 'contenu') |
argv | Arguments CLI parsés | argv.verbose |
dotenv | Chargement de fichier .env | dotenv.config('.env') |
Paquets npm exposés : chalk (couleurs), fs (fs-extra), os, path, YAML (yaml), minimist.
Ressources
- references/api.md — Référence complète de l'API : options
$,cd(),fetch(),question(),sleep(),echo(),stdin(),within(),retry(),spinner(),glob(),which(),ps,kill(),tmpdir(),tmpfile(),minimist,argv,chalk,fs,os,path,YAML,dotenv,quote(),useBash(),usePowerShell(),usePwsh() - references/configuration.md — Toutes les options
$.options:shell,prefix,postfix,quote,verbose,quiet,env,cwd,timeout,nothrow,detached,preferLocal,spawn,kill,log,input,signal,stdio,halt,delimiter,defaults - references/cli.md — Utilisation de la CLI : drapeaux, variables d'environnement, scripts Markdown, scripts distants, exécution depuis stdin, mode REPL
- references/process.md — Cycle de vie de ProcessPromise/ProcessOutput, piping, terminaison, abandon, formateurs de sortie, gestion des flux