zx
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    🐚 zx

    #!/usr/bin/env zx
    
    await $`cat package.json | grep name`
    
    let 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`,
    ])
    
    let name = 'foo bar'
    await $`mkdir /tmp/${name}`

    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.

    Install

    npm i -g zx

    Requirement

    Node.js >= 14.8.0

    Documentation

    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.

    $`command`

    Executes a given string using the spawn function from the child_process package and returns ProcessPromise<ProcessOutput>.

    let count = parseInt(await $`ls -1 | wc -l`)
    console.log(`Files count: ${count}`)

    For example, to upload files in parallel:

    let hosts = [...]
    await Promise.all(hosts.map(host =>
      $`rsync -azP ./src ${host}:/var/www`  
    ))

    If the executed program returns a non-zero exit code, ProcessOutput will be thrown.

    try {
      await $`exit 1`
    } catch (p) {
      console.log(`Exit code: ${p.exitCode}`)
      console.log(`Error: ${p.stderr}`)
    }

    ProcessPromise

    class ProcessPromise<T> extends Promise<T> {
      readonly stdin: Writable
      readonly stdout: Readable
      readonly stderr: Readable
      readonly exitCode: Promise<number>
      pipe(dest): ProcessPromise<T>
    }

    The pipe() method can be used to redirect stdout:

    await $`cat file.txt`.pipe(process.stdout)

    Read more about pipelines.

    ProcessOutput

    class ProcessOutput {
      readonly stdout: string
      readonly stderr: string
      readonly exitCode: number
      toString(): string
    }

    Functions

    cd()

    Changes the current working directory.

    cd('/tmp')
    await $`pwd` // outputs /tmp

    fetch()

    A wrapper around the node-fetch package.

    let resp = await fetch('http://wttr.in')
    if (resp.ok) {
      console.log(await resp.text())
    }

    question()

    A wrapper around the readline package.

    Usage:

    let bear = await question('What kind of bear is best? ')
    let token = await question('Choose env variable: ', {
      choices: Object.keys(process.env)
    })

    In second argument, array of choices for Tab autocompletion can be specified.

    function question(query?: string, options?: QuestionOptions): Promise<string>
    type QuestionOptions = { choices: string[] }

    sleep()

    A wrapper around the setTimeout function.

    await sleep(1000)

    nothrow()

    Changes behavior of $ to not throw an exception on non-zero exit codes.

    function nothrow<P>(p: P): P

    Usage:

    await nothrow($`grep something from-file`)
    
    // Inside a pipe():
    
    await $`find ./examples -type f -print0`
      .pipe(nothrow($`xargs -0 grep something`))
      .pipe($`wc -l`)

    If only the exitCode is needed, you can use the next code instead:

    if (await $`[[ -d path ]]`.exitCode == 0) {
      ...
    }
    
    // Equivalent of:
    
    if ((await nothrow($`[[ -d path ]]`)).exitCode == 0) {
      ...
    }

    Packages

    Next packages is available without importing inside scripts.

    chalk package

    The chalk package.

    console.log(chalk.blue('Hello world!'))

    fs package

    The fs-extra package.

    let content = await fs.readFile('./package.json')

    os package

    The os package.

    await $`cd ${os.homedir()} && mkdir example`

    minimist package

    The minimist package.

    Available as global const argv.

    Configuration

    $.shell

    Specifies what shell is used. Default is which bash.

    $.shell = '/usr/bin/bash'

    Or use a CLI argument: --shell=/bin/bash

    $.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')

    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 node
    import {$} from '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 (examples/markdown.md):

    zx examples/markdown.md

    TypeScript scripts

    The zx can compile .ts scripts to .mjs and execute them.

    zx examples/typescript.ts

    In TypeScript file include the zx package to import types:

    import 'zx'

    Or reference the zx package via:

    /// <reference types="zx"/>

    Example:

    #!/usr/bin/env zx
    import 'zx'
    
    void async function () {
      await $`ls -la`
    }()

    Executing remote scripts

    If the argument to the zx executable starts with https://, the file will be downloaded and executed.

    zx https://medv.io/example-script.mjs

    License

    Apache-2.0

    Disclaimer: This is not an officially supported Google product.

    Keywords

    none

    Install

    npm i zx

    DownloadsWeekly Downloads

    9,792

    Version

    2.0.0

    License

    Apache-2.0

    Unpacked Size

    37 kB

    Total Files

    7

    Last publish

    Collaborators

    • avatar
    • avatar