AGENTS.md — for coding agents working on merjs

What is this?

merjs is a Next.js-style web framework written in Zig. Zero Node.js. File-based routing, SSR, type-safe APIs, WASM client logic, Cloudflare Workers deploy.

Zig pin: 0.17.0-dev.1862+40ebd8162 (build.zig.zon minimum_zig_version). Download from https://ziglang.org/download/ (master / builds).

Project structure

src/              Framework runtime (the library)
  mer.zig         Public API surface — thin re-exports
  server.zig      HTTP server, dev endpoints, error overlay
  router.zig      Route matching + dispatch
  session.zig     HMAC session sign/verify
  fetch.zig       SSR HTTP client (single + parallel)
  html.zig        Comptime HTML builder DSL
  static.zig      Static file serving from public/
  watcher.zig     File watcher + SSE hot reload
  main.zig        Server entry point (not app-specific)

build/            Build system modules
  helpers.zig     addDirModules, addWasmExe
  examples.zig    Example project targets
  tools.zig       Tailwind auto-download
  packages.zig    Package test wiring

examples/site/    Demo app (merlionjs.com) — NOT framework code
  app/            Page routes (*.zig → SSR HTML)
  api/            API routes (*.zig → JSON)
  wasm/           Client WASM modules
  public/         Static assets
  worker/         Cloudflare Workers config

cli.zig           `mer` CLI (init, dev, build, add, update)
build.zig         Top-level build — delegates to build/

Quick commands

# Build & run the demo site
zig build codegen       # scan app/ + api/, generate route table
zig build serve         # dev server on :3000 with hot reload

# With verbose request logging
zig build serve -- --verbose

# Build CLI
zig build cli

# Build WASM modules
zig build wasm

# Build for Cloudflare Workers
zig build worker

# Run tests
zig build test

# Full production build
zig build prod

Debugging

Dev endpoints (only active in dev mode)

• http://localhost:3000/_mer/debug — shows all routes, framework version, Zig version, route counts
• http://localhost:3000/_mer/debug?format=json — same as above, machine-readable JSON
• http://localhost:3000/_mer/events — SSE hot reload stream

Production endpoints (always available)

• GET /_mer/health — liveness probe, returns {"status":"ok",...} JSON
• GET /_mer/ready — readiness probe, same payload (separate path for k8s)

Environment variables for deployment

• PORT — listening port (PaaS standard: Fly, Render, Railway, Heroku, Cloud Run inject this)
• HOST — bind interface; defaults to 0.0.0.0 in --no-dev, 127.0.0.1 in dev
• MERJS_DEV=0 — disable hot reload (equivalent to --no-dev)

Verbose mode

Run with --verbose to log every request with timing:

info(server): GET / 266µs
info(server): GET /api/hello 42µs
info(server): GET /counter 891µs

Error overlay

When a route handler errors in dev mode, the browser shows a styled error page with:

• The error name (e.g. OutOfMemory)
• The request path
• Debugging tips
• Framework version

In production (--no-dev), errors log to stderr and return a clean 500.

Common issues

Telemetry (Sentry + Datadog)

Both are opt-in via env vars — zero overhead when not configured.

Sentry (error tracking):

SENTRY_DSN=https://your-key@sentry.io/your-project-id

Route handler errors are automatically reported with error name, request path, and framework version.

Datadog (request metrics via DogStatsD):

DD_AGENT_HOST=127.0.0.1
DD_DOGSTATSD_PORT=8125    # default

Sends per-request timing (merjs.request.duration) and error counts (merjs.request.error) with path/method/status tags.

Docker

docker build -t merjs .
docker run -p 3000:3000 merjs

Adding routes

1. Create app/mypage.zig (page) or api/myendpoint.zig (API)
2. Export pub fn render(req: mer.Request) mer.Response
3. Run zig build codegen to regenerate the route table
4. zig build serve picks it up

Key conventions

• Pages return HTML: return mer.html("<h1>Hello</h1>");
• APIs return JSON: return mer.json("{\"ok\":true}");
• Use mer.h.div(...) for comptime HTML builder
• Use mer.dhi.Model(...) for request validation
• Use pub const meta: mer.Meta = .{ .title = "..." } for SEO
• Layouts: export from app/layout.zig, pages auto-wrap
• Dynamic routes: app/users/[id].zig → /users/:id