hex

hex

An opinionated Go application framework.

hex is an IoC container, service providers with a proper lifecycle, a typed event bus, layered config, structured logging, an HTTP server, a view engine, an embedded Lua runtime, a queue, a scheduler, a policy engine, feature flags, i18n, and telemetry — behind coherent interfaces that compose. A scaffolding CLI generates full projects and individual pieces (providers, controllers, migrations, commands) following the same conventions the framework enforces at runtime.

Write your business logic. Let hex handle the rest.

Install

hex has two install paths depending on what you want.

The hex CLI scaffolder — for creating new projects and generating code:

# Homebrew (macOS + Linux, recommended):
brew tap jordanbrauer/hex https://github.com/jordanbrauer/hex
brew install jordanbrauer/hex/hex

# Or via the Go toolchain:
go install github.com/jordanbrauer/hex/cmd/hex@latest

The framework packages — imported by your app's go.mod:

go get github.com/jordanbrauer/hex@latest

You almost never do this by hand — hex init generates a go.mod with the right require line, and hex make adds any subpackages your choices pull in.

Scaffold a new project:

hex init myproject --db sqlite --web
cd myproject
go run . serve

Point a browser at http://localhost:8080.

What's in the box

A quick tour

Bootstrap an app.

package main

import (
    "context"
    "os"

    "github.com/jordanbrauer/hex"
    hexcli "github.com/jordanbrauer/hex/cli"
    hexlog "github.com/jordanbrauer/hex/log"

    "myproject/app"
    "myproject/app/command"
)

func main() {
    hexlog.Init()

    kernel := hex.New()
    if err := app.Boot(kernel); err != nil {
        hexlog.Fatal("register providers", "error", err)
    }

    ctx := context.Background()
    if err := kernel.Bootstrap(ctx); err != nil {
        hexlog.Fatal("bootstrap", "error", err)
    }
    defer func() { _ = kernel.Shutdown(ctx) }()

    os.Exit(hexcli.Execute(command.Root(kernel)))
}

Write a service provider.

type Users struct{ provider.Base }

func (p *Users) Register(app provider.Application) error {
    app.Singleton("users", func(c *container.Container) (any, error) {
        db, err := container.Make[*sql.DB](c, "db")
        if err != nil {
            return nil, err
        }
        return NewUserService(db), nil
    })
    return nil
}

Test a route end-to-end.

client := webtest.New(t, app)

client.Get("/dashboard").
    StatusIs(200).
    See("Welcome, Alice").
    Find(".user-card").HasClass("active").
    Find("button").Count(3)

Examples

Runnable example apps under examples/:

• examples/bare-hex-app — the structural floor of a hex app: main.go and app/ only — no config, no docs, no dev tooling, no empty placeholder directories. A single Lua provider backs the baseline run/repl/version commands every hex app gets for free.
• examples/swapi — a Star Wars API demo, scaffolded via hex init, serving the classic SWAPI dataset out of a SQLite file.
• examples/ai-lua — a minimal app that boots hex/ai + hex/lua and executes Lua scripts that call an LLM through the agent module.

Documentation

• docs/PLAN.md — the framework's scope and package roster.
• docs/adr/ — architecture decisions, numbered and written in past tense. Read the ADR covering the area you're touching before changing it.
• docs/repl.md — user-facing REPL reference.
• docs/designs/ — design docs for work-in-flight proposals.
• CONTEXT.md — hex-specific vocabulary (App, Container, Binding, Provider, Bootstrap, Disk, Cache, Job, Pool, …). Use this vocabulary in code and prose.

Requirements

• Go 1.26 or newer.
• No cgo requirements in the base install. SQLite uses modernc.org/sqlite (pure Go), so cross-compilation from macOS to Linux "just works".

Contributing

Pull requests welcome. Read CONTRIBUTING.md for the process and AGENTS.md if you're an AI coding agent touching the codebase.

Every PR must pass just check — gofmt, go vet, golangci-lint, and the race-enabled test suite. CI mirrors that gate.

Status

hex is pre-1.0. The core packages are stable in shape; minor breaking changes may still land ahead of a 1.0 tag. Watch the repository or subscribe to release notifications if you're building on top of it.

Inspiration & references

hex stands on the shoulders of many prior frameworks and libraries. Direct influences:

• Laravel — the service container, service provider lifecycle, and artisan-style scaffolder.
• Phoenix — the runtime environment as a first-class concept, the layered supervisor tree feel of the provider registry, and channel-flavoured event bus semantics.
• Ruby on Rails — convention over configuration, generators, and the "one canonical place for each concern" project layout.
• Hugo — proof that Go can carry an opinionated framework with a great CLI.
• Algernon — a Go web server that embeds gopher-lua alongside markdown and templates, and did the gopher-lua ↔ Go-modules dance long before hex.

Notable Go libraries hex builds on:

• labstack/echo — HTTP routing and middleware.
• spf13/cobra and spf13/viper — CLI and config.
• charmbracelet/log and the wider charm TUI ecosystem.
• yuin/gopher-lua — the embedded Lua VM, plus Teal and Fennel on top of it.
• casbin/casbin — the authorisation model.
• golang-migrate/migrate — database migrations.
• cuelang.org/go — config schema validation.

Full list of dependencies and the ADR that motivated each wrapping decision is in docs/adr/.

License

hex is MIT-licensed — see LICENSE.

Several third-party projects are vendored into the tree (the Fennel compiler, the Teal compiler, and the algernon-patched Lua 5.2 compat shims that let Teal run inside gopher-lua). Their own licenses and notices live alongside their source under lua/{fennel,teal}/ and are indexed by THIRD_PARTY_NOTICES.md. If you redistribute hex, you must carry those notices with you.