Documentation	DeepWiki	Coverage	Build Status
zerofmk.in

Zero is a strongly opinionated web framework written in Zig, built on top of http.zig that aims for zero allocations and created to make development easier while keeping performance and observability in mind.

Zero framework is completely configurable, you may isolate and attach best-in-class built-in solutions as you see fit using the 12 Factor App methodology.

Zero framework has useful features like drop-in support for numerous databases, queuing systems, and external services, as well as REST, authentication, logging, metrics, observability, and scheduling.

Zero mascot

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Project Structure
• Configuration
• Examples
• Testing
• Benchmark
• Zig Version Compatibility
• Known Gotchas
• Attributions
• License

Features

Category	Status	Details
REST / CRUD	✅	Build standard REST endpoints out-of-box
Configuration	✅	.env with per-environment overrides
Logging	✅	Structured, UTC timestamps
Metrics	✅	App, HTTP, SQL, KV + process/memory stats
Tracing	✅	TraceID middleware, request-level tracing
Auth Middleware	✅	Basic, API Key, OAuth 2.0
CORS	✅	Configurable CORS middleware
Panic Recovery	✅	Automatic panic recovery
Databases	✅	PostgreSQL, SQLite, Redis
Pub/Sub	✅	MQTT, Kafka (via librdkafka)
Migrations	✅	DB migrations + seed on startup
HTTP Client	✅	Register multiple external services
Cron Jobs	✅	* * * * * + second-level + range support
WebSockets	✅	Built-in WebSocket support
Static Files	✅	Serve static assets + Swagger UI
Health Checks	✅	Liveness + status endpoints

See feature_parity.md for the full roadmap and upcoming features.

Requirements

• Zig 0.15.1 (tested and production baseline)
• librdkafka — required for Kafka support:

  sudo apt install librdkafka-dev   # Linux
  brew install librdkafka           # macOS

Installation

Add zero to your project:

zig fetch --save https://github.com/im-ng/zero/archive/refs/heads/main.zip

Quick Start

1. Initialize your project

mkdir zero-web-app && cd zero-web-app
zig init
zig fetch --save https://github.com/im-ng/zero/archive/refs/heads/main.zip

2. Configure build.zig

const zero = b.dependency("zero", .{});

const exe = b.addExecutable(.{
    .name = "myapp",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    }),
});

exe.root_module.addImport("zero", zero.module("zero"));
b.installArtifact(exe);

3. Create config directory

mkdir configs
touch configs/.env

4. Write your app

const std = @import("std");
const zero = @import("zero");

const App = zero.App;
const Context = zero.Context;

pub const std_options: std.Options = .{
    .logFn = zero.logger.custom,
};

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();

    const app = try App.new(allocator);
    try app.get("/json", jsonResponse);
    try app.run();
}

pub fn jsonResponse(ctx: *Context) !void {
    try ctx.json(.{ .msg = "hello from zero!" });
}

5. Run

zig build run

 INFO [03:23:39] Loaded config from file: ./configs/.env
 INFO [03:23:39] Starting server on port: 8080

See full documentation for detailed guides on authentication, databases, cron jobs, websockets, and more.

Project Structure

Directory	Purpose
src/datasource/	PostgreSQL (SQL), Redis (Cache)
src/pubsub/	MQTT and Kafka publishers/subscribers
src/cronz/	Cron scheduler and job execution
src/migration/	Database migrations and seeding
src/mw/	Middleware: auth, tracing, websocket
src/service/	HTTP client for external services
src/http/	Error types and HTTP utilities
src/zsutil/	System utils: memory, CPU, process, host
src/static/	Embedded Swagger UI assets

Key entry points:

• src/zero.zig — re-exports all public types
• src/app.zig — main App struct (App.new(), app.run())
• src/context.zig — request context with .SQL, .Cache, .GetService()

Configuration

Zero loads config from configs/.env at startup, with per-environment overrides (e.g. configs/.dev.env when APP_ENV=dev).

# Application
APP_NAME=myapp
APP_VERSION=1.0.0
APP_ENV=dev

# Logging
LOG_LEVEL=debug

# PostgreSQL
# DB_HOST=localhost
# DB_USER=user1
# DB_PASSWORD=password1
# DB_NAME=mydb
# DB_PORT=5432
# DB_DIALECT=postgres

# Redis
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379
# REDIS_USER=redis
# REDIS_PASSWORD=password
# REDIS_DB=0
# REDIS_TLS_ENABLED=false

# Kafka
# KAFKA_BROKER=localhost:9092

# MQTT
# MQTT_HOST=localhost
# MQTT_PORT=1883

# Authentication
# AUTH_MODE=Basic

All keys are commented out by default; features activate only when uncommented. See config.md for the full list.

Examples

14 example applications are available in the examples/ directory:

Example	Description
zero-basic	Minimal HTTP server
zero-auth	Authentication (Basic, API Key, OAuth)
zero-cronz	Cron job scheduling
zero-kafka-publisher	Kafka message publishing
zero-kafka-subscriber	Kafka message consumption
zero-mqtt-publisher	MQTT message publishing
zero-mqtt-subscriber	MQTT message consumption
zero-redis	Redis cache operations
zero-sqlite	SQLite database usage
zero-migration	Database migrations
zero-service-client	External HTTP service client
zero-stream	Streaming responses
zero-todo-htmx	HTMX-powered CRUD app
zero-websocket	WebSocket connections

Each example has its own build.zig and build.zig.zon.

Testing

zig build test              # run all unit tests (52 tests)
zig build --release=fast    # release build
make clean                  # remove build artifacts

Benchmark

Configuration	Requests/sec
Metrics + logging + tracing + info logging	~16,500
Metrics + logging + tracing	~29,800
Metrics + logging (no tracing)	~31,000
No metrics	~31,200

Baseline (none log level): ~83,000 req/s over 100s with 100 concurrent connections.

❯ go-wrk -c 100 -d 100 http://localhost:8080/json
Running 100s test @ http://localhost:8080/json
  100 goroutine(s) running concurrently
8344879 requests in 1m39.643117619s, 1.39GB read
Requests/sec:		83747.67
Transfer/sec:		14.30MB
Overall Requests/sec:	83430.16
Overall Transfer/sec:	14.24MB
Fastest Request:	84µs
Avg Req Time:		1.193ms
Slowest Request:	19.669ms
Number of Errors:	0
10%:			124µs
50%:			150µs
75%:			164µs
99%:			175µs
99.9%:			176µs
99.9999%:		176µs
99.99999%:		176µs
stddev:			743µs

Zig Version Compatibility

Version	Compiles	Tests	Runtime	Notes
0.15.1	✅	52/52	✅	Production baseline
0.15.2	✅	52/52	✅	Production
0.16.0	❌	N/A	N/A	Build system API changed

Known Gotchas

• rdkafka is linked as a weak system library — builds fail without librdkafka-dev
• Always rm -rf .zig-cache zig-out zig-pkg/ before switching Zig versions
• src/cronz/scheduler.zig and src/mw/authProvider.zig use @import("../zero.zig") (relative path), not @import("zero")

Attributions

See attribution.md for details.

License

Apache License