# Ziex

> Full-stack web framework for Zig. Compile-time safety, deterministic performance, absolute simplicity, and a delightful developer experience.

ZX files use familiar HTML-style markup with full access to Zig control flow (`if`/`else`, `for`/`while`, `switch`). File-system routing, API routes, WebSockets, component/page caching, KV storage, and SQLite are built in. Deploy as a standalone binary, WASI edge module, or static site.

Important notes:

- ZX is stricter than HTML: all tags must be closed (including self-closing tags like `<br />`)
- Components and pages receive an allocator (usually `ctx.arena` for request-scoped allocations)
- File-system routing maps `pages/` and `routes/` to URLs; dynamic segments use `[param]` folders

## Docs
- [Learn](https://ziex.dev/learn): Quick start covering core ZX concepts
- [Reference](https://ziex.dev/reference): Language and API reference
- [Examples](https://ziex.dev/examples): Interactive feature demos
- [Playground](https://ziex.dev/playground): Try ZX in the browser
- [GitHub](https://github.com/ziex-dev/ziex): Source repository

## Examples

### Control Flow

#### if

```zx
const ControlIfProps = struct { is_admin: bool };
pub fn ControlIf(
    allocator: zx.Allocator,
    props: ControlIfProps,
) zx.Component {
    return (
        <div @{allocator}>
            {if (props.is_admin) (
                <span>Admin</span>
            ) else (
                <span>Member</span>
            )}
        </div>
    );
}
```

#### if optional capture

```zx
pub fn ControlIfOptional(allocator: zx.Allocator) zx.Component {
    const maybe_name: ?[]const u8 = "Zig";
    return (
        <div @{allocator}>
            {if (maybe_name) |name| (<span>{name}</span>)}
        </div>
    );
}
```

#### if error capture

```zx
pub fn ControlIfError(allocator: zx.Allocator) zx.Component {
    const parsed =
        std.fmt.parseInt(u32, "42", 10);

    return (
        <div @{allocator}>
            {if (parsed) |value| (
                <span>{value}</span>
            ) else |err| (
                <span>{@errorName(err)}</span>
            )}
        </div>
    );
}
```

#### switch

```zx
const Role = enum { admin, member, guest };
const ControlSwitchProps = struct { role: Role };
pub fn ControlSwitch(allocator: zx.Allocator, props: ControlSwitchProps) zx.Component {
    return (
        <div @{allocator}>
            {switch (props.role) {
                .admin => (<span>Admin</span>),
                .member => (<span>Member</span>),
                else => (<span>Guest</span>),
            }}
        </div>
    );
}
```

#### for

```zx
const ControlForProps = struct { items: []const []const u8 };
pub fn ControlFor(allocator: zx.Allocator, props: ControlForProps) zx.Component {
    return (
        <ul @{allocator}>
            {for (props.items) |item| (<li>{item}</li>)}
        </ul>
    );
}
```

#### while

```zx
pub fn ControlWhile(allocator: zx.Allocator) zx.Component {
    var i: usize = 0;
    return (
        <ul @{allocator}>
            {while (i < 3) : (i += 1) (<li>Item {i + 1}</li>)}
        </ul>
    );
}
```

#### while optional capture

```zx
pub fn ControlWhileOptional(allocator: zx.Allocator) zx.Component {
    var maybe: ?u32 = 1;
    return (
        <ul @{allocator}>
            {while (maybe) |value| : (maybe = if (value < 3) value + 1 else null) (
                <li>{value}</li>
            )}
        </ul>
    );
}
```

#### while error capture

```zx
pub fn ControlWhileError(allocator: zx.Allocator) zx.Component {
    var n: u32 = 1;
    return (
        <div @{allocator}>
            {while (parseOnce(&n)) |value| (
                <span>{value}<br /></span>
            ) else |err| (
                <span>{@errorName(err)}</span>
            )}
        </div>
    );
}

fn parseOnce(n: *u32) !u32 {
    if (n.* < 100) {
        n.* += 1;
        return n.*;
    }
    return error.Done;
}
```

### Caching

#### component

```zx
pub fn CacheComponent(
    allocator: zx.Allocator,
) !zx.Component {
    return (<Slow @{allocator} @caching="10s" />);
}

fn Slow(allocator: zx.Allocator) !zx.Component {
    try std.Io
        .sleep(zx.io(), .fromSeconds(2), .awake);
    return (<div @{allocator}>Slow</div>);
}
```

#### page

```zx
pub fn Caching__Page(
    ctx: zx.PageContext,
) !zx.Component {
    try std.Io
        .sleep(zx.io(), .fromSeconds(2), .awake);
    return (
        <div @allocator={ctx.arena}>
            <h1>Expensive Page</h1>
            <p>I take too long to load.</p>
        </div>
    );
}

pub const CachingPage__options = zx.PageOptions{
    .caching = .{ .ttl = .fromSeconds(300) },
};
```

### File System Routing

#### page

```zx
pub fn Routing__Page(
    ctx: zx.PageContext,
) zx.Component {
    return (
        <div @allocator={ctx.arena}>
            <h1>Home</h1>
        </div>
    );
}
```

#### layout

```zx
pub fn Layout(
    ctx: zx.LayoutContext,
    children: zx.Component,
) zx.Component {
    return (
        <html @allocator={ctx.arena}>
            <body>
                {children}
            </body>
        </html>
    );
}
```

### Component

#### basics

```zx
const ButtonProps = struct { label: []const u8 };
pub fn Button(
    ctx: *zx.ComponentCtx(ButtonProps),
) zx.Component {
    return (
        <button @allocator={ctx.allocator}>
            Click {ctx.props.label}
        </button>
    );
}
```

#### fragment

```zx
pub fn Fragment(
    allocator: zx.Allocator,
) zx.Component {
    return (
        <fragment @{allocator}>
            <span>One</span>
            <>
                <p>Two</p><p>Three</p>
            </>
        </fragment>
    );
}
```

#### props

```zx
pub fn SpreadProps(
    allocator: zx.Allocator,
) zx.Component {
    const attrs =
        .{ .class = "btn", .id = "cta" };
    const class = "primary";
    return (
        <section @{allocator}>
            <button {..attrs}>Spreading</button>
            <button {class}>Shorthand</button>
        </section>
    );
}
```

#### attr

```zx
pub fn DynamicAttr(
    allocator: zx.Allocator,
) zx.Component {
    const is_active = true;
    const class = if (is_active) "active" else "idle";
    const color = if (is_active) "green" else "red";
    return (
        <section @{allocator}>
            <button class={class}>Go</button>
            <button style=`color: {color};`>
                Template String
            </button>
        </section>
    );
}
```

### Dynamic Path

```zx
pub fn Page(ctx: zx.PageContext) zx.Component {
    const id = ctx.request.params.get("id");
    return (
        <section @allocator={ctx.arena}>
            <h1>User {id}</h1>
        </section>
    );
}
```

### Expressions

```zx
pub fn Expressions(allocator: zx.Allocator) zx.Component {
    const name = "Alice";
    const count: u32 = 42;
    const price: f32 = 19.99;
    const active = true;
    return (
        <main @allocator={allocator}>
            <p>{name}</p>
            <p>{count}</p>
            <p>${price}</p>
            <p>{active}</p>
        </main>
    );
}
```

### Builtin Attributes

#### allocator

```zx
pub fn AllocatorDemo(ctx: zx.PageContext) zx.Component {
    const message = "Allocator is inherited by children";
    return (
        <main @allocator={ctx.arena}>
            <section>
                <h2>{message}</h2>
                <p>Use ctx.arena for request-scoped allocations.</p>
            </section>
        </main>
    );
}
```

#### escaping

```zx
pub fn RawHtml(allocator: zx.Allocator) zx.Component {
    const trusted = "<strong>Trusted HTML</strong>";
    return (
        <main @allocator={allocator}>
            <div>{trusted}</div>
            <div @escaping={.none}>{trusted}</div>
        </main>
    );
}
```

### Importing

```zx
pub fn ImportDemo(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <ControlIf is_admin={true} />
            <ControlSwitch role={Role.member} />
        </main>
    );
}
```

### Component

#### children

```zx
const CardChildrenProps = struct { title: []const u8, children: zx.Component };
pub fn CardDemo(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <Card title="Welcome">
                <p>This content is passed as children.</p>
            </Card>
        </main>
    );
}

fn Card(allocator: zx.Allocator, props: CardChildrenProps) zx.Component {
    return (
        <div @allocator={allocator} class="card">
            <h2>{props.title}</h2>
            <div>{props.children}</div>
        </div>
    );
}
```

### API Route

```zx
pub fn PUT(ctx: zx.RouteContext) !void {
    try ctx.response.json(.{ .status = "ok" }, .{});
}

pub fn POST(ctx: zx.RouteContext) !void {
    const Data = struct { id: u32 };
    const data =
        try ctx.request.json(Data, .{});

    try ctx.response.json(.{
        .id = if (data) |d| d.id else 0,
        .created = true,
    }, .{});
}
```

### WebSocket

```zx
pub fn GET(ctx: zx.RouteContext) !void {
    try ctx.socket.upgrade({});
}

pub fn Socket(ctx: zx.SocketContext) !void {
    try ctx.socket.write(
        try ctx.fmt("{s}", .{ctx.message}),
    );
}

pub fn SocketOpen(ctx: zx.SocketOpenContext) !void {
    try ctx.socket.write("Opened!");
}
```

### Client-side Rendering

```zx
pub fn Client(allocator: zx.Allocator) zx.Component {
    return (<Counter @{allocator} @rendering={.client} />);
}
pub fn Counter(ctx: *zx.ComponentCtx(void)) zx.Component {
    const count = ctx.state(i32, 0);
    return (
        <div @allocator={ctx.allocator} class="counter">
            <button onclick={ctx.bind(increment)}>
                Click Me: {count}
            </button>
        </div>
    );
}
fn increment(e: *zx.client.Event.Stateful) void {
    const count = e.state(i32);
    count.set(count.get() + 1);
}
```

### Plugin

#### tailwind

```zx
pub fn buildTailwind(b: *std.Build) !void {
    const exe = b.addExecutable(.{ .name = "my-app" });
    var zx_build = try ziex.init(b, exe, .{});
    var assetsdir = zx_build.assetsdir;
    zx_build.plugin(
        zx.plugins.tailwind(b, .{
            .input = b.path("app/assets/style.css"),
            .output = assetsdir.path(b, "style.css"),
        }),
    );
}
```

#### esbuild

```zx
pub fn buildEsbuild(b: *std.Build) !void {
    const exe = b.addExecutable(.{ .name = "my-app" });
    var zx_build = try ziex.init(b, exe, .{});
    var assetsdir = zx_build.assetsdir;
    zx_build.plugin(
        zx.plugins.esbuild(b, .{
            .input = b.path("app/main.ts"),
            .output = assetsdir.path(b, "main.js"),
        }),
    );
}
```

### Learn

#### greeting

```zx
pub fn Learn__HelloWorld(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <h1>Welcome to my app</h1>
            <Learn__Greeting />
        </main>
    );
}

fn Learn__Greeting(allocator: zx.Allocator) zx.Component {
    return (<p @allocator={allocator}>Hello, World!</p>);
}
```

#### markup

```zx
pub fn Learn__AboutSection(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <h1>About</h1>
            <p>Hello there.<br />How are you?</p>
            <Learn__AboutCard />
        </main>
    );
}

fn Learn__AboutCard(allocator: zx.Allocator) zx.Component {
    return (
        <div @allocator={allocator} class="card">
            <h2>User Profile</h2>
            <p>Welcome to the card component!</p>
        </div>
    );
}
```

#### text expression

```zx
pub fn Learn__UserGreeting(allocator: zx.Allocator) zx.Component {
    const user_name = "Alice";
    const greeting = "Welcome back";
    return (
        <main @allocator={allocator}>
            <h1>{greeting}, {user_name}!</h1>
            <p>Your profile is ready.</p>
        </main>
    );
}
```

#### format expression

```zx
pub fn Learn__ProductInfo(allocator: zx.Allocator) zx.Component {
    const price: f32 = 19.99;
    const quantity: u32 = 3;
    const is_available = true;
    return (
        <main @allocator={allocator}>
            <p>Price: ${price}</p>
            <p>Quantity: {quantity}</p>
            <p>Available: {is_available}</p>
        </main>
    );
}
```

#### conditional

```zx
pub fn Learn__UserStatus(allocator: zx.Allocator) zx.Component {
    const is_logged_in = true;
    const is_admin = false;
    return (
        <main @allocator={allocator}>
            {if (is_logged_in) (<p>Welcome back!</p>) else (<p>Please log in.</p>)}
            {if (is_admin) (<button>Admin Panel</button>)}
        </main>
    );
}
```

#### switch

```zx
const Learn__Role = enum { admin, member, guest };
pub fn Learn__RoleBadge(allocator: zx.Allocator) zx.Component {
    const role: Learn__Role = .admin;
    return (
        <main @allocator={allocator}>
            <span class="badge">
                {switch (role) {
                    .admin => (<strong>Admin</strong>),
                    .member => ("Member"),
                    .guest => ("Guest"),
                }}
            </span>
        </main>
    );
}
```

#### list

```zx
pub fn Learn__ProductList(allocator: zx.Allocator) zx.Component {
    const products = [_][]const u8{ "Apple", "Banana", "Orange" };
    return (
        <main @allocator={allocator}>
            <h2>Products</h2>
            <ul>{for (products) |product| (<li>{product}</li>)}</ul>
        </main>
    );
}
```

#### props

```zx
const Learn__ButtonProps = struct {
    title: []const u8 = "Click Me",
    class: []const u8 = "btn",
};
pub fn Learn__ButtonDemo(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <Learn__Button title="Submit" class="primary" />
            <Learn__Button title="Cancel" />
            <Learn__Button />
        </main>
    );
}

fn Learn__Button(allocator: zx.Allocator, props: Learn__ButtonProps) zx.Component {
    return (<button @allocator={allocator} class={props.class}>{props.title}</button>);
}
```

#### page

```zx
pub fn Learn__Page(ctx: zx.PageContext) zx.Component {
    return (
        <main @allocator={ctx.arena}>
            <h1>About Us</h1>
            <p>Welcome to our website!</p>
            <p>Path: {ctx.request.pathname}</p>
        </main>
    );
}
```

#### layout

```zx
pub fn Learn__Layout(ctx: zx.LayoutContext, children: zx.Component) zx.Component {
    return (
        <html @allocator={ctx.arena}>
            <head><title>My App</title></head>
            <body>
                <nav><a href="/">Home</a> <a href="/about">About</a></nav>
                <main>{children}</main>
                <footer>© My App</footer>
            </body>
        </html>
    );
}
```

#### build manual

```zx
pub fn Learn__build(b: *std.Build) !void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    const app_exe = b.addExecutable(.{
        .name = "ziex_app",
        .root_module = b.createModule(.{
            .root_source_file = b.path("app/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    _ = try ziex.init(b, app_exe, .{});
}
```

#### dynamic route

```zx
pub fn Learn__UserProfile(ctx: zx.PageContext) zx.Component {
    const user_id = ctx.request.params.get("id") orelse "unknown";
    return (
        <main @allocator={ctx.arena}>
            <h1>User Profile</h1>
            <p>User ID: {user_id}</p>
        </main>
    );
}
```

#### fragment

```zx
pub fn Learn__FragmentDemo(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <>
                <h1>Welcome</h1>
                <p>Multiple elements without a wrapper</p>
            </>
        </main>
    );
}
```

#### children

```zx
const Learn__CardProps = struct { title: []const u8, children: zx.Component };
pub fn Learn__CardDemo(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <Learn__Card title="Welcome">
                <p>This content is passed as children.</p>
                <button>Click me</button>
            </Learn__Card>
        </main>
    );
}

fn Learn__Card(allocator: zx.Allocator, props: Learn__CardProps) zx.Component {
    return (
        <div @allocator={allocator} class="card">
            <h2>{props.title}</h2>
            <div class="card-body">{props.children}</div>
        </div>
    );
}
```

#### dynamic attributes

```zx
pub fn Learn__DynamicAttrs(allocator: zx.Allocator) zx.Component {
    const class_name = "primary-btn";
    const user_id = "user-123";
    const is_active = true;
    return (
        <main @allocator={allocator}>
            <button class={class_name} id={user_id}>Submit</button>
            <div class={if (is_active) "active" else "inactive"}>Dynamic class</div>
        </main>
    );
}
```

#### onclick

```zx
pub fn Learn__Interactivity(allocator: zx.Allocator) zx.Component {
    return (<Learn__EventHandling @{allocator} @rendering={.client} />);
}
pub fn Learn__EventHandling(allocator: zx.Allocator) zx.Component {
    return (
        <main @allocator={allocator}>
            <button onclick={Learn__handleClick}>Click me</button>
            <input oninput={Learn__handleInput} />
        </main>
    );
}

fn Learn__handleClick(_: zx.client.Event) void {
    zx.log.info("Clicked!", .{});
}

fn Learn__handleInput(event: zx.client.Event) void {
    const v = event.value() orelse "";
    zx.log.info("Input: {s}", .{v});
}
```

### Reference Inline

#### attrs

```zx
pub fn unwrap__template_attrs() void {
    const count = 42;
    const name = "John";
    // ...
    _ = (
        <div class=`item-{count}` data-user=`user-{name}`>
            <a href=`/users/{name}/profile`>Profile</a>
        </div>
    );
    // Renders:
    //<div class="item-42" data-user="user-John">
    //  <a href="/users/John/profile">Profile</a>
    //</div>
}
```

#### expr string

```zx
pub fn unwrap__ref_expr_string() void {
    const name = "Alice";
    // ...
    _ = (<p>{name}</p>); // <p>Alice</p>
}
```

#### expr int

```zx
pub fn unwrap__ref_expr_int() void {
    const count: u32 = 42;
    // ...
    _ = (<p>{count}</p>); // <p>42</p>
}
```

#### expr float

```zx
pub fn unwrap__ref_expr_float() void {
    const price: f32 = 19.99;
    // ...
    _ = (<p>${price}</p>); // <p>$19.99</p>
}
```

#### expr bool

```zx
pub fn unwrap__ref_expr_bool() void {
    const active = true;
    // ...
    _ = (<p>{active}</p>); // <p>true</p>
}
```

#### expr enum

```zx
pub fn unwrap__ref_expr_enum() void {
    const Status = enum { pending, approved, rejected };
    const status = Status.approved;
    // ...
    _ = (<p>{status}</p>); // <p>approved</p>
}
```

#### expr optional

```zx
pub fn unwrap__ref_expr_optional() void {
    const maybe_name: ?[]const u8 = "Bob";
    // ...
    _ = (<p>{maybe_name}</p>); // <p>Bob</p>

    const no_name: ?[]const u8 = null;
    // ...
    _ = (<p>{no_name}</p>); // <p></p> (empty)
}
```

#### expr component

```zx
pub fn unwrap__ref_expr_component() void {
    const header = zx.Component{ .text = "Header" };
    // ...
    _ = (<div>{header}</div>); // Renders the Header component
}
```

#### expr component array

```zx
pub fn unwrap__ref_expr_component_array() void {
    const items: []const zx.Component = &.{ zx.Component{ .text = "A" }, zx.Component{ .text = "B" } };
    // ...
    _ = (<ul>{items}</ul>); // Renders both Item components
}
```

#### optional capture

```zx
pub fn unwrap__ref_optional_capture() void {
    const user_name: ?[]const u8 = "Alice";
    // ...
    _ = if (user_name) |name| (<p>Welcome, {name}!</p>);

    // With else branch:
    _ = if (user_name) |name| (<p>Hello, {name}</p>) else (<p>Guest</p>);

    // While with capture (iterator pattern):
    var maybe_item: ?[]const u8 = "item";
    _ = while (maybe_item) |item| : (maybe_item = null) (<li>{item}</li>);
}
```

#### error capture

```zx
pub fn unwrap__ref_error_capture() void {
    const parsed = std.fmt.parseInt(u32, "42", 10);

    // If with error capture:
    _ = if (parsed) |value| (<p>Value: {value}</p>) else |err| (<p>Error: {@errorName(err)}</p>);

    // While with error capture:
    var first = true;
    _ = while (parseOnceRefInline(&first)) |value| (<li>{value}</li>) else |err| (<p>Iteration ended: {@errorName(err)}</p>);
}

fn parseOnceRefInline(first: *bool) !u32 {
    if (first.*) {
        first.* = false;
        return 1;
    }
    return error.Done;
}
```

#### spread attrs

```zx
pub fn unwrap__ref_spread_attrs() void {
    const form_attrs = .{
        .class = "form-control",
        .@"data-validate" = "true",
    };
    const input_props = .{ .name = "email", .value = "test@example.com" };
    // ...
    _ = (
        <form {..form_attrs}>
            <input type="text" {..input_props} />
        </form>
    );
}
```

#### shorthand attrs

```zx
pub fn unwrap__ref_shorthand_attrs() void {
    const class = "btn-primary";
    const disabled = true;
    const @"data-id" = "123";
    _ = (<button {class} {disabled} {@"data-id"}>Click</button>);
    // Renders: <button class="btn-primary" disabled data-id="123">Click</button>
}
```

#### template attrs

```zx
pub fn unwrap__ref_template_attrs() void {
    const count = 42;
    const name = "John";
    // ...
    _ = (
        <div class=`item-{count}` data-user=`user-{name}`>
            <a href=`/users/{name}/profile`>Profile</a>
        </div>
    );
    // Renders:
    //<div class="item-42" data-user="user-John">
    //  <a href="/users/John/profile">Profile</a>
    //</div>
}
```

#### component context

```zx
pub fn RefInlineNoProps__Container(ctx: *zx.ComponentContext) zx.Component {
    return (
        <div @allocator={ctx.allocator}>
            {ctx.children}
        </div>
    );
}
```

#### component ctx props

```zx
pub const RefInline__CardProps = struct { title: []const u8 };
pub fn RefInline__Card(ctx: *zx.ComponentCtx(RefInline__CardProps)) zx.Component {
    return (
        <article @allocator={ctx.allocator}>
            <h2>{ctx.props.title}</h2>
            {ctx.children}
        </article>
    );
}
```

#### multiline strings

```zx
pub fn unwrap__ref_multiline_strings() void {
    // Multiline strings use Zig's \\ syntax:
    _ = (
        <pre>
            {
            \\const x = 1;
            \\const y = 2;
            \\const sum = x + y;
        }
        </pre>
    );
}
```

#### comments

```zx
pub fn unwrap__ref_comments() void {
    // Single-line comments are supported in ZX:
    _ = (
        <div>
            // This is a comment
            <p>Visible content</p>
            // Another comment
        </div>
    );
}
```

#### route ctx

```zx
pub fn RefInline__GET(ctx: zx.RouteContext) !void {
    _ = ctx.request; // Request details
    _ = ctx.response; // Set headers, body, json, etc.
    _ = ctx.socket; // WebSocket upgrade and pub/sub
    _ = ctx.arena; // Request-scoped allocator
}
```

#### socket ctx

```zx
pub fn RefInline__Socket(ctx: zx.SocketContext) !void {
    _ = ctx.socket; // WebSocket interface
    _ = ctx.message; // Received message data
    _ = ctx.data; // Custom data from upgrade
    _ = ctx.arena; // Message-scoped allocator
}
```

#### component caching basic

```zx
pub fn unwrap__ref_component_caching_basic() void {
    // Cache for 10 seconds
    _ = (<header @caching="10s" />);

    // Cache for 5 minutes
    _ = (<aside @caching="5m" />);

    // Cache for 1 hour
    _ = (<footer @caching="1h" />);

    // Cache for 1 day
    _ = (<section @caching="1d" />);
}
```

#### component caching key

```zx
pub fn unwrap__ref_component_caching_key() void {
    // Cache with a custom key for manual invalidation
    _ = (<section @caching="10m:user-profile" />);

    // Cache navigation with key
    _ = (<nav @caching="1h:main-nav" />);
}
```

#### page caching

```zx
pub fn RefPageCaching__Page(ctx: zx.PageContext) zx.Component {
    return (
        <div @allocator={ctx.arena}>
            <h1>Cached Page</h1>
            <p>This page is cached for 5 minutes.</p>
        </div>
    );
}

// Enable page-level caching
pub const RefPageCaching__options = zx.PageOptions{
    .caching = .{ .ttl = .fromSeconds(300) }, // 5 minutes
};
```

#### layout caching

```zx
pub fn Ref__Layout(ctx: zx.LayoutContext, children: zx.Component) zx.Component {
    return (
        <html @allocator={ctx.arena}>
            <body>
                {children}
            </body>
        </html>
    );
}

// Cache the entire layout for 1 hour
pub const RefLayout__options = zx.LayoutOptions{
    .caching = .{ .ttl = .fromSeconds(3600) },
};
```

#### cache invalidation

```zx
pub fn unwrap__ref_cache_invalidation() void {
    // Delete a specific cache entry by key
    _ = zx.cache.del("cmp:user-profile");

    // Delete all entries matching a prefix
    // Useful for invalidating related content
    _ = zx.cache.delPrefix("cmp:user") catch 0;
}
```

### Learn

#### state management

```zx
pub fn Learn__StateDemo(allocator: zx.Allocator) zx.Component {
    return (<Learn__StatePanel @allocator={allocator} @rendering={.client} />);
}

pub fn Learn__StatePanel(ctx: *zx.ComponentCtx(void)) zx.Component {
    const count = ctx.state(i32, 0);
    const title = ctx.state([]const u8, "Hello");
    return (
        <div @allocator={ctx.allocator}>
            <h1>App State: {title.get()}</h1>
            <p>Count: {count.get()}</p>
            <button onclick={count.bind(Learn__incrementCount)}>Increment Count</button>
        </div>
    );
}

fn Learn__incrementCount(value: i32) i32 {
    return value + 1;
}
```

#### api route

```zx
pub fn Learn__GET(ctx: zx.RouteContext) !void {
    try ctx.response.json(.{ .message = "Hello World!" }, .{});
}
```

#### enable kv

```zx
pub fn Learn__enableKvInit(b: *std.Build, app_exe: *std.Build.Step.Compile) !void {
    _ = try ziex.init(b, app_exe, .{
        .app = .{
            .features = .{
                .kv = .enabled,
            },
        },
    });
}
```

#### enable db

```zx
pub fn Learn__enableDbInit(b: *std.Build, app_exe: *std.Build.Step.Compile) !void {
    _ = try ziex.init(b, app_exe, .{
        .app = .{
            .features = .{
                .sqlite = .enabled,
            },
        },
    });
}
```

#### enable cache

```zx
pub fn Learn__enableCacheInit(b: *std.Build, app_exe: *std.Build.Step.Compile) !void {
    _ = try ziex.init(b, app_exe, .{
        .app = .{
            .features = .{
                .cache = .enabled,
            },
        },
    });
}
```

#### kv basic

```zx
pub fn Learn__KvBasic(ctx: zx.PageContext) !zx.Component {
    try zx.kv.put("greeting", "hello from kv", .{});
    const value = try zx.kv.get(ctx.arena, "greeting");
    try zx.kv.delete("greeting");

    return (
        <main @allocator={ctx.arena}>
            <p>Stored value: {value orelse "not found"}</p>
        </main>
    );
}
```

#### kv typed

```zx
pub fn Learn__KvTyped(ctx: zx.PageContext) !zx.Component {
    const User = struct {
        id: u32,
        name: []const u8,
        active: bool,
    };

    try zx.kv.putAs("user:123", User{
        .id = 123,
        .name = "alice",
        .active = true,
    }, .{});

    const user = try zx.kv.as(ctx.arena, "user:123", User);

    return (
        <main @allocator={ctx.arena}>
            {if (user) |u| (
                <p>User: {u.name} (#{u.id})</p>
            ) else (
                <p>Not found</p>
            )}
        </main>
    );
}
```

#### kv scoped

```zx
pub fn Learn__KvScoped(ctx: zx.PageContext) !zx.Component {
    const sessions = zx.kv.scoped(.sessions);
    try sessions.put("abc123", "token-xyz", .{});
    const token = try sessions.get(ctx.arena, "abc123");

    return (
        <main @allocator={ctx.arena}>
            <p>Session token: {token orelse "none"}</p>
        </main>
    );
}
```

#### db basic

```zx
pub fn Learn__DbBasic(ctx: zx.PageContext) !zx.Component {
    _ = try zx.db.run(
        \\CREATE TABLE IF NOT EXISTS posts (
        \\  id INTEGER PRIMARY KEY,
        \\  title TEXT NOT NULL
        \\)
    , .empty);

    _ = try zx.db.run("INSERT INTO posts (title) VALUES (?1)", .{"Hello World"});

    const row = try zx.db.get(ctx.arena, "SELECT title FROM posts ORDER BY id DESC LIMIT 1", .{});

    return (
        <main @allocator={ctx.arena}>
            <p>Latest post: {if (row) |r| r.text("title") else "none"}</p>
        </main>
    );
}
```

#### db typed

```zx
pub fn Learn__DbTyped(ctx: zx.PageContext) !zx.Component {
    const Post = struct {
        id: i64,
        title: []const u8,
    };

    _ = try zx.db.run(
        \\CREATE TABLE IF NOT EXISTS blog_posts (
        \\  id INTEGER PRIMARY KEY,
        \\  title TEXT NOT NULL
        \\)
    , .empty);

    _ = try zx.db.run("INSERT INTO blog_posts (title) VALUES (?1)", .{"ZX Guide"});

    const posts = try zx.db.rows(ctx.arena, Post, "SELECT id, title FROM blog_posts", .{});

    return (
        <main @allocator={ctx.arena}>
            {for (posts) |post| (
                <p>{post.title} (#{post.id})</p>
            )}
        </main>
    );
}
```

#### db transaction

```zx
pub fn Learn__DbTransaction(ctx: zx.PageContext) !zx.Component {
    const Account = struct { id: i64, balance: i64 };

    _ = try zx.db.run(
        \\CREATE TABLE IF NOT EXISTS accounts (
        \\  id INTEGER PRIMARY KEY,
        \\  balance INTEGER NOT NULL
        \\)
    , .empty);
    _ = try zx.db.run("INSERT OR REPLACE INTO accounts (id, balance) VALUES (1, 100), (2, 100)", .empty);

    try zx.db.transaction({}, transfer);

    const accounts = try zx.db.rows(ctx.arena, Account, "SELECT id, balance FROM accounts ORDER BY id", .{});

    return (
        <main @allocator={ctx.arena}>
            {for (accounts) |account| (
                <p>Account #{account.id}: {account.balance}</p>
            )}
        </main>
    );
}

fn transfer(_: void, db: zx.Db) !void {
    _ = try db.run("UPDATE accounts SET balance = balance - 10 WHERE id = ?1", .{1});
    _ = try db.run("UPDATE accounts SET balance = balance + 10 WHERE id = ?1", .{2});
}
```

#### template attrs

```zx
pub fn unwrap__learn_template_attrs() void {
    const id = 42;
    // ...
    _ = (<a href=`/users/{id}/profile`>Profile</a>);
}
```

#### spread attrs

```zx
pub fn unwrap__learn_spread_attrs() void {
    const attrs = .{ .class = "btn", .disabled = true };
    // ...
    _ = (<button {..attrs}>Click</button>);
}
```

#### client action

```zx
pub fn ContactForm(ctx: *zx.ComponentCtx(void)) zx.Component {
    return (
        <form @allocator={ctx.allocator} action={ctx.bind(ContactForm__onSubmit)}>
            <input type="text" name="message" />
            <button type="submit">Send</button>
        </form>
    );
}

fn ContactForm__onSubmit(a: *zx.client.Action.Stateful) void {
    const data = a.data(struct { message: []const u8 });
    zx.log.info("message: {s}", .{data.message});
}
```

#### server action

```zx
pub fn LoginForm(allocator: zx.Allocator) zx.Component {
    return (
        <form @allocator={allocator} action={onLogin}>
            <input type="text" name="username" />
            <button type="submit">Log in</button>
        </form>
    );
}

fn onLogin(a: zx.server.Action) void {
    const data = a.data(struct { username: []const u8 });
    zx.log.info("username: {s}", .{data.username});
}
```

### Reference Inline

#### csr simple handler

```zx
fn handleInput(event: zx.client.Event) void {
    const value = event.value() orelse "";
    zx.log.info("Input: {s}", .{value});
}
// Attach: oninput={handleInput}
```

#### csr stateful handler

```zx
pub fn CsrStateful__Counter(ctx: *zx.ComponentCtx(void)) zx.Component {
    const count = ctx.state(i32, 0);
    return (
        <div @allocator={ctx.allocator}>
            <button onclick={ctx.bind(CsrStateful__increment)}>{count}</button>
        </div>
    );
}
fn CsrStateful__increment(e: *zx.client.Event.Stateful) void {
    const count = e.state(i32); // same order as ctx.state()
    count.set(count.get() + 1);
}
```

#### csr state bind

```zx
pub fn CsrStateBind__Counter(ctx: *zx.ComponentCtx(void)) zx.Component {
    const count = ctx.state(i32, 0);
    return (
        <div @allocator={ctx.allocator}>
            <button onclick={count.bind(CsrStateBind__increment)}>{count}</button>
        </div>
    );
}
fn CsrStateBind__increment(value: i32) i32 {
    return value + 1;
}
```

## Optional

- [Framework comparisons](https://ziex.dev/vs): Ziex vs other web frameworks
- [Sitemap](https://ziex.dev/sitemap.xml): All indexable pages