{"id":47622594,"url":"https://github.com/oliverandrich/burrow","last_synced_at":"2026-04-19T20:04:49.525Z","repository":{"id":343108500,"uuid":"1176301874","full_name":"oliverandrich/burrow","owner":"oliverandrich","description":"A modular Go web framework built on Chi, Bun/SQLite, and html/template — deploy as a single binary.","archived":false,"fork":false,"pushed_at":"2026-04-01T16:32:15.000Z","size":7789,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T06:27:42.716Z","etag":null,"topics":["bootstrap5","bun","golang","golang-library","sqlite","urfave-cli","webframework"],"latest_commit_sha":null,"homepage":"http://burrow.someonewho.codes/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oliverandrich.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T21:56:53.000Z","updated_at":"2026-04-01T16:32:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oliverandrich/burrow","commit_stats":null,"previous_names":["oliverandrich/burrow"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/oliverandrich/burrow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverandrich%2Fburrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverandrich%2Fburrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverandrich%2Fburrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverandrich%2Fburrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oliverandrich","download_url":"https://codeload.github.com/oliverandrich/burrow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverandrich%2Fburrow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31489427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap5","bun","golang","golang-library","sqlite","urfave-cli","webframework"],"created_at":"2026-04-01T22:23:58.105Z","updated_at":"2026-04-06T21:02:25.414Z","avatar_url":"https://github.com/oliverandrich.png","language":"Go","readme":"# Burrow\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/cover.jpg\" alt=\"Burrow — Go gophers building a modular burrow\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/oliverandrich/burrow/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/oliverandrich/burrow/ci.yml?branch=main\u0026label=CI\u0026style=for-the-badge\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/oliverandrich/burrow/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/oliverandrich/burrow?style=for-the-badge\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://go.dev/\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/oliverandrich/burrow?style=for-the-badge\" alt=\"Go Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/oliverandrich/burrow\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/oliverandrich/burrow?style=for-the-badge\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/oliverandrich/burrow?style=for-the-badge\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://burrow.readthedocs.io/\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-burrow.readthedocs.io-blue?style=for-the-badge\" alt=\"Docs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nA web framework for Go developers who want something like Django, Rails, or Flask — but with the deployment simplicity of a single static binary.\n\nMost Go web development follows the \"API backend + SPA frontend\" pattern. Burrow takes a different approach: server-rendered HTML with templates, modular apps with their own routes and middleware, and a document database that just works. Deploy with embedded SQLite as a single binary, or connect to PostgreSQL for scale — same code, same API.\n\nBuilt on [Chi](https://go-chi.io/), [Den](https://github.com/oliverandrich/den) (ODM with SQLite and PostgreSQL backends), and Go's standard `html/template`. Ideal for self-hosted applications, internal tools, or any project where \"download, start, use\" is the goal.\n\n\u003e [!TIP]\n\u003e **Why *Burrow*?** A burrow is a network of interconnected chambers — each with its own purpose, yet part of a larger whole. That's exactly how the framework works: pluggable apps are the rooms, and your gophers live in them.\n\n\u003e [!NOTE]\n\u003e Burrow is designed for server-rendered web applications, not API-only services. If you're building a JSON API with a separate frontend, a lighter router like Chi on its own is probably a better fit.\n\n## Features\n\n- **App-based architecture** — build your application from composable, self-contained apps\n- **SQLite or PostgreSQL** — embedded SQLite (pure Go, no CGO) for single-binary deploys, or PostgreSQL for scale — switch with one flag\n- **Automatic schema** — document types declared in code, tables and indexes created on startup\n- **Standard templates** — Go's `html/template` with a global template set, per-app FuncMaps, and automatic layout wrapping\n- **CSS-agnostic** — bring your own CSS framework (Bootstrap, Tailwind, etc.)\n- **Layout system** — app layout via server, admin layout via admin package\n- **CLI configuration** — flags, environment variables, and TOML config via [urfave/cli](https://github.com/urfave/cli)\n- **CSRF protection** — automatic token generation and validation\n- **Flash messages** — session-based flash message system\n- **Bootstrap integration** — Bootstrap 5 CSS/JS, inline SVG icons, htmx, and dark mode theme switcher\n- **Contrib apps** — auth (WebAuthn/passkeys), sessions, i18n, admin, CSRF, flash messages, jobs, uploads, rate limiting, healthcheck, static files\n\n## Quick Start\n\n```bash\nmkdir myapp \u0026\u0026 cd myapp\ngo mod init myapp\ngo get github.com/oliverandrich/burrow@latest\n```\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \"net/http\"\n    \"os\"\n\n    \"github.com/oliverandrich/burrow\"\n    \"github.com/go-chi/chi/v5\"\n    \"github.com/urfave/cli/v3\"\n)\n\n// homeApp is a minimal app with a single route.\ntype homeApp struct{}\n\nfunc (a *homeApp) Name() string { return \"home\" }\nfunc (a *homeApp) Routes(r chi.Router) {\n    r.Method(\"GET\", \"/\", burrow.Handle(func(w http.ResponseWriter, r *http.Request) error {\n        return burrow.Text(w, http.StatusOK, \"Hello from Burrow!\")\n    }))\n}\n\nfunc main() {\n    srv := burrow.NewServer(\n        \u0026homeApp{},\n    )\n\n    cmd := \u0026cli.Command{\n        Name:   \"myapp\",\n        Flags:  srv.Flags(nil),\n        Action: srv.Run,\n    }\n\n    if err := cmd.Run(context.Background(), os.Args); err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n```bash\ngo mod tidy\ngo run .\n```\n\nSee [`example/hello/`](example/hello/) for a minimal hello world app, or [`example/notes/`](example/notes/) for a complete example with auth, admin, i18n, and more.\n\n## Architecture\n\n```\ncontrib/        Reusable apps\n  admin/        Admin panel coordinator + ModelAdmin\n  auth/         WebAuthn passkeys, recovery codes, email verification\n  authmail/     Pluggable email renderer + SMTP implementation\n  bootstrap/    Bootstrap 5 CSS/JS/htmx assets, theme switcher, layout\n  bsicons/      Bootstrap Icons as inline SVG template functions\n  csrf/         CSRF protection\n  healthcheck/  Liveness and readiness probes\n  htmx/         htmx static asset + request/response helpers\n  i18n/         Locale detection and translations\n  jobs/         SQLite-backed background job queue\n  messages/     Flash messages\n  ratelimit/    Per-client rate limiting\n  session/      Cookie-based sessions\n  staticfiles/  Static file serving with content-hashed URLs\n  uploads/      File upload storage and serving\nexample/        Example applications (hello world, notes app)\n```\n\n### The App Interface\n\nEvery app implements `burrow.App`:\n\n```go\ntype App interface {\n    Name() string\n}\n```\n\nApps can optionally implement additional interfaces:\n\n| Interface | Purpose |\n|---|---|\n| `HasDocuments` | Register Den document types |\n| `HasRoutes` | Register HTTP routes |\n| `HasMiddleware` | Contribute middleware |\n| `HasNavItems` | Contribute navigation items |\n| `HasTemplates` | Contribute `.html` template files |\n| `HasFuncMap` | Contribute static template functions |\n| `HasRequestFuncMap` | Contribute request-scoped template functions |\n| `Configurable` | Define CLI flags and read configuration |\n| `HasCLICommands` | Contribute CLI subcommands |\n| `Seedable` | Seed the database with initial data |\n| `HasAdmin` | Contribute admin panel routes and nav items |\n| `HasStaticFiles` | Contribute embedded static file assets |\n| `HasTranslations` | Contribute translation files |\n| `HasDependencies` | Declare required apps |\n| `HasJobs` | Register background job handlers |\n| `PostConfigurable` | Second-pass configuration after all apps are configured |\n| `HasShutdown` | Clean up on graceful shutdown |\n\n### Layouts\n\nLayouts are template name strings. The app layout wraps user-facing pages:\n\n```go\nsrv.SetLayout(\"myapp/layout\")\n```\n\nThe admin layout is owned by the admin package:\n\n```go\nadmin.New(admin.WithLayout(\"custom/admin-layout\"))\n```\n\n`RenderTemplate` renders page content, then wraps it in the layout template with `.Content` set to the rendered fragment. Layout templates access dynamic data via template functions:\n\n```html\n{{ range navLinks }}...{{ end }}  {{/* filtered nav with active state */}}\n{{ if currentUser }}...{{ end }}  {{/* authenticated user */}}\n{{ csrfToken }}                   {{/* CSRF token for forms */}}\n```\n\n### Configuration\n\nConfiguration is resolved in order: CLI flags \u003e environment variables \u003e TOML file.\n\nCore flags include `--host`, `--port`, `--database-dsn`, `--log-level`, `--log-format`, `--tls-mode`, and more. Apps can contribute their own flags via the `Configurable` interface.\n\n### Document Registration\n\nApps declare their document types by implementing `HasDocuments`:\n\n```go\nfunc (a *App) Documents() []any {\n    return []any{\u0026Poll{}, \u0026Choice{}}\n}\n```\n\nTables and indexes are created automatically on startup via Den's `Register()`. No SQL migration files needed.\n\n## Development\n\n```bash\njust setup          # Check that all required dev tools are installed\njust test           # Run all tests\njust lint           # Run golangci-lint\njust fmt            # Format code\njust coverage       # Generate coverage report\njust tidy           # Tidy module dependencies\njust example-hello  # Run the hello world example\njust example-notes  # Run the notes example application\n```\n\nRequires Go 1.25+. Run `just setup` to verify your dev environment.\n\n## Documentation\n\nFull documentation is available in the [`docs/`](docs/) directory.\n\n## License\n\nBurrow is licensed under the [MIT License](LICENSE).\n\nThe Go Gopher was originally designed by [Renee French](https://reneefrench.blogspot.com/) and is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).\n\nThird-party licenses are listed in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliverandrich%2Fburrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foliverandrich%2Fburrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliverandrich%2Fburrow/lists"}