tanGO is a small, explicit web framework for Go, inspired by Django's ergonomics but built from plain Go structs and interfaces. Write models as structs, get typed migrations, a server-rendered admin and a JSON API from the same code. Scaffolding writes plain Go you own: nothing is generated at runtime, boot never scans your filesystem, and there is no hidden configuration.
Status: pre-1.0, released as v0.x. The Covered API in Versioning and compatibility is what a release promises not to break; a minor release may still break it, only after the deprecation window, and says so in the changelog. Anything marked "planned" or "future" in the docs is not built yet. Read Limitations before depending on tanGO for anything beyond what it says it does.
go install github.com/angvp/tango/cmd/tango@latest
tango newproject shop
cd shop
go run .tango newproject scaffolds a go.mod, a main.go pre-wired for SQLite and the admin app, a project package where your apps are listed, and a shell program for tango shell, and it runs unchanged. Run tango makemigrations, tango migrate and tango admin create <username> to create your first admin account, then open /admin/ (the project prints its address when it starts).
To add tanGO to an existing module instead, run go get github.com/angvp/tango. The tango CLI is optional but recommended: it wraps go run/go build with a few conventions the framework expects your main.go to implement.
The server-rendered admin over two models, from examples/api-with-admin.
The fastest way to see a complete application is examples/jsonapi: a separate Go module whose one app answers a JSON route. Its main.go is written by hand, so it shows every line of a small application. Its app registers one named route:
func (App) Register(registry *tango.Registry) error {
return registry.Routes().Include("/greetings/", tango.URLs{
tango.Path("GET", "/{name}/", hello, tango.Name("hello")),
})
}
func hello(ctx *tango.Context) error {
name := ctx.Param("name")
return ctx.JSON(200, map[string]string{"message": "Hello, " + name + "!"})
}Run it:
cd examples/jsonapi
go run .
curl http://localhost:8000/greetings/World/
# {"message":"Hello, World!"}tango newapp greetings scaffolds an app stub like this one and prints the line that installs it: adding it to InstalledApps in project/project.go is one line you write yourself, because tanGO never edits your code for you. tango shell opens a Go prompt on your models and database for looking at, or fixing, a few rows.
- Explicit lifecycle:
Config,AppandRegistry; nothing boots implicitly. - Routing: named routes with reverse lookup, built on chi internally (chi is never part of your imports), and
Contexthelpers for JSON, request binding and redirects. - Models from structs: a handful of tags (
tango:"pk",tango:"unique",tango:"index",tango:"fk=Other") and no schema DSL. - Persistence:
db.Storefor CRUD, queries and raw SQL on SQLite, PostgreSQL or MySQL, with foreign keys, two-layer validation and cascade delete. See relationships and admin foreign keys. - Typed Go migrations:
tango makemigrations,migrateandmigrate down. - Admin: server-rendered list, create, edit and delete with pagination, search, filters and ordering, behind a session-cookie login with CSRF protection and a rate-limited login. Accounts are managed with
tango admin create/resetpassword/deactivate. - Batteries, each optional: accounts with password reset, email verification and a JSON mode for single-page apps; SMTP
mail;storagewith local-disk and S3 stores;cachewith in-process, Redis and Memcached stores; WebSocket rooms; a token-bucket rate limiter. - OpenAPI 3.1 generated from your routes, with Swagger UI (
openapi.New, oropenapi.Devto serve it only while developing). - A CLI (
tango run/check/makemigrations/openapi/migrate/newproject/newapp/tui/shell/admin) that wraps ordinarygo buildandgo runrather than replacing them.
If writing normal Go is simpler than invoking tanGO, write normal Go.
- Prefer Go primitives before replacing them.
- Prefer explicit structure over convention magic.
- Treat JSON and API-only apps as first-class. HTML is optional.
- The admin is a normal app, not a privileged subsystem.
- No custom template language.
- Third-party internals stay behind tanGO's abstractions.
- Tutorial — build one application, a bulletin board, from an empty directory to a deployed container in ten parts: routing and JSON views, persistence and migrations, the HTML admin, foreign keys, server-rendered pages, accounts and forms, API tokens and rate limits, a live WebSocket feed, background jobs and graceful shutdown, and testing and deployment.
- Guides — standalone, task-oriented references: project structure, application architecture, configuration, models and tags, routing,
Context, persistence, migrations, admin, app checks, security headers and Content-Security-Policy, OpenAPI documentation, background jobs, accounts, mail, uploads, caching, rate limiting, realtime, dialect setup, reusable apps, and relationships/admin foreign keys. - API reference — the supported public surface, linked to runnable examples. Generated package docs are also available via
go docor pkg.go.dev. - Examples, each with a README giving its purpose and commands:
jsonapi: the smallest JSON application, one hand-written app;api-with-admin: a JSON API and the HTML admin over one set of models, linked by a foreign key;notes-starter: a keepable starter with generated migrations, the admin and rate limiting;jwt-api: a JSON route behind stateless bearer JWTs;realtime-chat: WebSocket rooms with JWT auth and graceful shutdown;accounts-mail: theaccountsapp's password reset and email verification, with emails printed to the terminal;spa-accounts: the backend of a single-page app:accounts' JSON mode with bearer tokens, a host profile written in the registration transaction, a JSON field edited in the admin, and boundedvarcharfields;uploads: a document locker:storage.Uploadreads one multipart file, the host keeps the generated key in its own model, andstorage.Servedelivers it to its owner, on the local disk;cache:cache.FetchJSONover a bounded in-process cache for a recomputable read, with a versioned prefix and a fail-open hook;reusable-greetingsandreusable-greetings-host: a reusable app with contributed migrations and static assets, and a host installing it;board: the tutorial's finished application, deployable as a container.
- Versioning and compatibility — what each release promises not to break, deprecations, and the changelog.
- Limitations — non-goals, security boundaries, and dialect differences.
- Upgrading — what a host application changes in each release.
Bug reports and focused pull requests are welcome; CONTRIBUTING.md covers setup and what a change needs, and SECURITY.md covers reporting a vulnerability.
Documentation in this repository is checked, not just written: every checked-in example under examples/ is built as its own module in CI, so a stale command or import path in a doc snippet gets caught rather than silently drifting from what actually runs. Run the same check locally before sending a documentation change:
go test ./...scripts/check.sh runs everything CI runs (the Redis and Memcached adapter tests need a server and skip without TANGO_TEST_REDIS_URL and TANGO_TEST_MEMCACHE_ADDR): gofmt, vet, build, the tests and the offline link check (with lychee, or its pinned Docker image when lychee is not installed).
TestExamplesAreIndependentModulesThatCompile (at the repository root) builds every examples/* module and runs its generated -check flag; the migration-generation tests in internal/cli similarly go build a real generated migrations package rather than only inspecting its source text.
MIT — see LICENSE.
