Getting Started

1. Install Zig 0.16.0

Weld's only toolchain dependency is the Zig compiler. Install Zig 0.16.0 and make sure zig is on your PATH:

zig version   # -> 0.16.0

2. Build the Weld compiler

From the repository root:

zig build                 # -> zig-out/bin/weld
# or, directly:
zig build-exe src/main.zig -femit-bin=weld

You now have a weld binary. Run the compiler's own tests with zig build test.

3. Write your first service

Create hello.weld:

route GET "/" {
    type "text/html"
    respond "<h1>Welcome to Weld</h1>\n"
}

route GET "/hello" {
    respond "Hello, world!\n"
}

route GET "/health" {
    status 200
    respond "OK\n"
}

4. Run it

The one-shot path compiles a .weld service straight to a native binary and runs it:

./weld hello.weld --emit bin -O ReleaseFast
./hello &
curl localhost:8080/hello
# Hello, world!

--emit bin invokes zig for you to produce the binary. Pass -O ReleaseFast, ReleaseSafe, or ReleaseSmall through to Zig; use --port to change the listen port and -o NAME to name the output.

Emit Zig instead

Prefer to drive the toolchain yourself? Emit Zig and compile it:

./weld hello.weld -o hello.zig --port 9090
zig build-exe hello.zig -O ReleaseFast

Cross-compile

Because Weld emits Zig, cross-compilation is a single flag:

./weld hello.weld --emit bin --target aarch64-linux -o hello-arm64
./weld hello.weld --emit bin --target riscv64-linux -o hello-rv64

--target is host-independent — Weld drives Zig's cross-compiler, so any host can build for any target, and Zig supplies the target's libc (so driver sqlite services, which compile the bundled SQLite amalgamation, cross-compile too).

From Windows

The weld compiler ships for Linux, macOS, and Windows (weld.exe). On Windows you develop as usual and cross-compile your service for wherever it will run:

# Build a Linux x86-64 server binary from a Windows machine:
weld.exe app.weld --emit bin --target x86_64-linux -o app

The generated server targets POSIX (Linux/macOS), so producing a native Windows server — --emit bin with no --target on Windows — isn't supported yet; always pass a Linux or macOS --target. Everything else works natively on Windows: --emit zig, the TypeScript / JavaScript clients, weld fmt, and weld import. See the CLI reference for the platform matrix.

Add a test

Write test "name" { … assert cond … } blocks alongside your code and run them with weld --emit test. Tests compile away in the server binary.

fn clamp(x: int, lo: int, hi: int) -> int {
    if x < lo { return lo }
    if x > hi { return hi }
    return x
}

test "clamp bounds a value" {
    assert clamp(5, 0, 10) == 5
    assert clamp(-3, 0, 10) == 0
    assert clamp(99, 0, 10) == 10
}

./weld app.weld --emit test    # generates a Zig test file and runs it (CI-ready)

Next: the Language Guide.