ZX - Fast Web Framework for Zig

Command Line Interface

ZX comes with a built-in CLI tool to help you manage your project.

Installation

Install the ZX CLI using one of the following methods:

Linux/macOS

curl -fsSL https://ziex.dev/install | bash

Windows

powershell -c "irm ziex.dev/install.ps1 | iex"

Installing Zig

brew install zig # macOS
winget install -e --id zig.zig # Windows

See for other platforms →

Commands

init

zx init [flags]

Initialize a new ZX project in the current directory. This command creates all the necessary files and directory structure to get started with ZX.

Flags
  • --template, -t name

    Template to use (default: "default"). Available options:

    • default: Basic ZX project template
    • react: ZX project with React client-side components support
Note: The command will skip initialization if build.zig.zon already exists in the current directory.

dev

zx dev [flags]

Start the app in development mode with hot reloading. This command watches for changes in your files and automatically rebuilds the project when changes are detected. It also builds TypeScript/JavaScript files if present.

Flags
  • --binpath, -b path

    Binpath of the app in case you have multiple executable artifacts or are using a custom zig-out directory (default: empty, auto-detected)

  • --build-args args

    Additional build arguments to pass to zig build (space-separated)

Example
zx dev --build-args "--release-fast"

serve

zx serve [flags]

Serve the project for production. This command builds and runs the executable, starting the development server.

Flags
  • --port, -p number

    Port to run the server on (default: 3000)

Example
zx serve --port 8080

transpile

zx transpile path [flags]

Transpile .zx files to Zig source code. This is useful for debugging, inspecting the generated code, or understanding how ZX transforms your JSX-like syntax into Zig.

Arguments
  • path

    Path to .zx file or directory containing .zx files (required)

Flags
  • --outdir, -o directory

    Output directory for transpiled Zig files (default: ".zx")

Examples
# Transpile a single file
zx transpile site/pages/page.zx

# Transpile a directory
zx transpile site/pages --outdir site/.zx

# Transpile and output to stdout (when using default outdir with a file)
zx transpile site/pages/page.zx

fmt

zx fmt [path] [flags]

Format ZX source code files. This command automatically formats your .zx files according to ZX's formatting rules. (Alpha)

Arguments
  • [path]

    Path to .zx file or directory (optional, formats current directory if not specified)

Flags
  • --stdio

    Read from stdin and write formatted output to stdout

  • --stdout

    Write formatted output to stdout instead of modifying files on disk

Examples
# Format all .zx files in current directory
zx fmt

# Format a specific file
zx fmt site/pages/page.zx

# Format and output to stdout
zx fmt site/pages/page.zx --stdout

# Format from stdin
cat file.zx | zx fmt --stdio

export

zx export [flags]

Generate static site assets. This command builds your project and exports it as a static site, generating HTML files for all routes. Useful for deploying to static hosting services.

Flags
  • --outdir, -o directory

    Output directory for exported static files (default: "dist")

  • --binpath, -b path

    Binpath of the app executable (default: auto-detected)

Example
zx export --outdir ./build
Note: Make sure to run zig build first to build the ZX executable before exporting.

update

zx update [flags]

Update the version of the ZX dependency in your project's build.zig.zon file. This updates the ZX library version used by your project, not the CLI tool itself.

Flags
  • --version, -v version

    Version to update to (default: "latest"). Can be a specific version like 0.0.1-dev.307 or "latest" for the latest release

Examples
# Update to latest version
zx update

# Update to specific version
zx update --version 0.0.1-dev.307

upgrade

zx upgrade [flags]

Upgrade the version of the ZX CLI tool itself. This downloads and installs a new version of the CLI binary.

Flags
  • --version, -v version

    Version to upgrade to (default: "latest"). Can be a specific version like 0.0.1-dev.307 or "latest" for the latest release

Examples
# Upgrade to latest version
zx upgrade

# Upgrade to specific version
zx upgrade --version 0.0.1-dev.307
Note: After upgrading, the command will automatically display the new version.

version

zx version

Show the current version of the ZX CLI tool. This command displays the installed CLI version, which may differ from the ZX library version used in your project.