Hanzo Base - Open Source Backend for Any App

package main

import (
    "log"

    "github.com/hanzoai/base"
    "github.com/hanzoai/base/core"
)

func main() {
    app := base.New()

    app.OnServe().BindFunc(func(se *core.ServeEvent) error {
        // registers new "GET /hello" route
        se.Router.GET("/hello", func(re *core.RequestEvent) error {
            return re.String(200, "Hello world!")
        })

        return se.Next()
    })

    if err := app.Start(); err != nil {
        log.Fatal(err)
    }
}

go mod init myapp && go mod tidy
go run main.go serve

# Download from releases or build from source
CGO_ENABLED=0 go build -o base ./examples/base
./base serve --http=0.0.0.0:8080 --dir=./hz_data

docker run -d \
  --name base \
  -p 8080:8080 \
  -v ./hz_data:/pb_data \
  ghcr.io/hanzoai/base \
  serve --http=0.0.0.0:8080 --dir=/pb_data

┌──────────────────────────────────────────────┐
│              Hanzo Base Binary                │
├──────────────┬───────────────┬───────────────┤
│   REST API   │  Realtime WS  │  Admin UI     │
│   /api/*     │  /api/realtime│  /_/          │
├──────────────┴───────────────┴───────────────┤
│                  core.App                     │
│  ┌─────────┐ ┌──────────┐ ┌───────────────┐ │
│  │ Records │ │ Auth     │ │ File Storage  │ │
│  │ (CRUD)  │ │ (OAuth2) │ │ (S3/local)    │ │
│  └─────────┘ └──────────┘ └───────────────┘ │
├──────────────────────────────────────────────┤
│  SQLite (default) │ PostgreSQL (cloudsql)    │
└──────────────────────────────────────────────┘

base/
  base.go              # Main Base struct, implements core.App
  core/                # Core app logic, records, collections, events, router
  apis/                # HTTP API handlers (records, auth, collections, realtime, batch, etc.)
  cmd/                 # CLI commands (serve, superuser)
  crdt/                # CRDT types (document, text, sync)
  forms/               # Form validation (record upsert, email, S3 test)
  migrations/          # Database migration scripts
  mails/               # Email templates
  plugins/
    jsvm/              # JavaScript VM (Goja) for hooks and migrations
    migratecmd/        # Migration CLI command
    cloudsql/          # Serverless PostgreSQL (per-tenant)
    functions/         # OpenFaaS serverless functions
    platform/          # Multi-tenant IAM + KMS integration
    scheduler/         # Cron/scheduled tasks
    ghupdate/          # GitHub self-update
    zap/               # ZAP binary protocol transport (port 9652)
  sdk/
    base-js/           # @hanzoai/base TypeScript SDK
    base-react/        # @hanzoai/base-react React hooks
  tools/               # Internal utility packages
    archive/           # Archive utilities
    auth/              # Auth helpers
    cron/              # Cron scheduler
    dbutils/           # Database utilities
    filesystem/        # File system abstraction
    hook/              # Event hook system
    inflector/         # String inflection
    list/              # List utilities
    logger/            # Structured logging
    mailer/            # Email sending
    osutils/           # OS utilities
    picker/            # Data picker
    router/            # HTTP router
    routine/           # Goroutine helpers
    search/            # Search utilities
    security/          # Security helpers
    store/             # In-memory store
    subscriptions/     # Realtime subscriptions
    template/          # Template engine
    tokenizer/         # Token utilities
    types/             # Custom types
  ui/                  # Admin dashboard (Svelte 4 + Vite 5)
  examples/base/       # Standalone example with all plugins
  tests/               # Integration tests
  docs/                # Documentation

./base serve              # Start the HTTP server
./base serve --dev        # Dev mode (verbose logging, SQL output)
./base serve --http=0.0.0.0:8080
./base serve --dir=./hz_data
./base superuser create   # Create a superuser
./base superuser upsert   # Create or update a superuser

--dir              Data directory (default: ./hz_data)
--dev              Enable dev mode
--encryptionEnv    Env var name for 32-char encryption key
--queryTimeout     Default SELECT query timeout in seconds

# Run tests
go test ./...
make test

# Lint
golangci-lint run -c ./golangci.yml ./...
make lint

# Build standalone binary
cd examples/base
CGO_ENABLED=0 go build

# Generate JS types for JSVM plugin
make jstypes

# Test coverage report
make test-report

cd ui
npm install
npm run dev     # Dev server at localhost:3000
npm run build   # Production build to ui/dist/

# Multi-stage build (from repo Dockerfile)
FROM golang:1.26-alpine AS builder
WORKDIR /build
COPY . .
CGO_ENABLED=0 go build \
  -ldflags="-s -w -X github.com/hanzoai/base.Version=$(git describe --tags)" \
  -o /build/base ./examples/base/main.go

FROM alpine:3.21
COPY --from=builder /build/base /app/base
EXPOSE 8080
ENTRYPOINT ["/app/base"]
CMD ["serve", "--http=0.0.0.0:8080", "--dir=/pb_data"]

import { BaseClient } from '@hanzoai/base';

const client = new BaseClient('http://localhost:8080');

// Reactive queries, query deduplication, optimistic updates
// Exports: core, react hooks, crdt

import { useBaseQuery } from '@hanzoai/base-react';

// Reactive queries, optimistic mutations, realtime, CRDT collaboration