hamr

Disclaimer

This library and cli is still in development and can/will change. Meaning, if you use this now, features might be deprecated and you might need to pin version.

HAMR

An opinionated Go full-stack framework and project scaffolding CLI. HAMR extracts proven patterns from production Go web applications into reusable packages and gives you a working project with one command.

hamr new

You get a production-ready Go + Templ + HTMX application (with optional Alpine.js) with sensible defaults, structured logging, database migrations, session auth, and AI-ready documentation baked in.

Documentation

• HAMR Guide -- Learn how to build with HAMR, from project setup through deployment
• Package Reference -- Full API docs for every hamr/pkg package
• CLI Reference -- All hamr commands and flags

What's in the box

HAMR is two things:

1. Framework library (pkg/) -- reusable Go packages your project imports
2. CLI tool (cmd/hamr/) -- scaffolds new projects that use the framework

Framework packages

CLI commands

Install

CLI tool

go install github.com/FyrmForge/hamr/cmd/hamr@latest

Framework packages

Import the packages you need in your go.mod:

go get github.com/FyrmForge/hamr@latest

Then import individual packages:

import (
    "github.com/FyrmForge/hamr/pkg/config"
    "github.com/FyrmForge/hamr/pkg/logging"
    "github.com/FyrmForge/hamr/pkg/server"
)

Quick start

# Install the CLI
go install github.com/FyrmForge/hamr/cmd/hamr@latest

# Create a new project
hamr new myproject

# Follow the prompts to choose:
#   - GitHub username/org (auto-detected from gh CLI)
#   - CSS approach (plain CSS with design system or Tailwind)
#   - Database (PostgreSQL)
#   - File storage (none, local, or S3/RustFS)
#   - WebSocket support
#   - E2E testing scaffold

# Run it
cd myproject
hamr dev                    # starts Postgres, builds, watches, live-reloads

Generated project structure

myproject/
├── cmd/
│   ├── server/              # Application entry point + Dockerfile
│   └── migrate/             # Database migration runner
├── internal/
│   ├── db/migrations/       # SQL migrations (embed.FS)
│   ├── repo/                # Data access layer (postgres/)
│   ├── service/             # Business logic (auth service)
│   ├── api/                 # JSON API handlers
│   └── web/
│       ├── server.go        # Routes and middleware stack
│       ├── handler/         # One package per domain (home/, auth/, errors/)
│       └── components/      # Shared Templ components and layout
├── static/                  # CSS, JS (vendored HTMX + idiomorph; Alpine if opted in), images
├── docs/                    # ADRs, feature specs, AI guides
├── docker/                  # Docker Compose for PostgreSQL
├── .github/workflows/       # CI and deploy pipelines
├── hamr.toml                # Dev server configuration
├── Makefile
├── CLAUDE.md                # Claude Code instructions
├── AGENTS.md                # AI coding conventions
└── go.mod

Stack

Architecture highlights

Per-group error pages -- middleware catches errors and renders templ components, with per-status-code overrides.

Identity is a string -- all framework packages accept subject IDs as string. Projects using int64, uuid.UUID, or a field called account_id provide their own conversion at the boundary.

Callback-based extensibility -- auth middleware uses a SubjectLoader callback, RBAC uses a RoleChecker callback. The framework never knows your user struct.

Development

# Build the CLI
make build

# Run tests
make test

# Lint
make lint

# Vet
make vet

Requirements

• Go 1.25 or later
• PostgreSQL 15+ (for generated projects)
• Docker (optional, for local Postgres via docker-compose)

License

Apache License 2.0. See LICENSE for details.