gobananas

README

🍌 go-bananas

The application framework for Go that is so simple, it's Bananas.

go-bananas is a lean, server-side-rendered (SSR) web framework plus a small application-infrastructure layer for Go. It is assembled from focused, composable packages — a template renderer, composable middleware, CSRF, secure-cookie sessions, flash messages, form binding/validation, a graceful HTTP server, and pluggable secrets/keys — so you import only what you need. A single pluggable Authenticator seam makes OIDC a wiring exercise, not a framework dependency, and configuration is plain env vars via go-envconfig.

It is extracted and generalized from Google's exposure-notifications-verification-server and exposure-notifications-server.

📚 Documentation

• Guides & getting started: https://mikehelmick.github.io/go-bananas
• API reference: https://pkg.go.dev/github.com/mikehelmick/go-bananas
• Runnable example: examples/ssr-oidc — a complete SSR + OIDC app.

Install

go-bananas requires Go 1.26 or newer.

go get github.com/mikehelmick/go-bananas@latest

Quick start

package main

import (
	"context"
	"embed"
	"net/http"

	"github.com/gorilla/mux"
	"github.com/mikehelmick/go-bananas/middleware"
	"github.com/mikehelmick/go-bananas/render"
	"github.com/mikehelmick/go-bananas/server"
	"github.com/mikehelmick/go-bananas/webctx"
)

//go:embed templates static
var assets embed.FS

func main() {
	ctx := context.Background()

	h, err := render.New(assets, render.WithDevMode(true))
	if err != nil {
		panic(err)
	}

	r := mux.NewRouter()
	r.Use(middleware.Recovery(h))
	r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		m := webctx.TemplateMapFromContext(req.Context())
		m.Title("Home")
		h.RenderHTML(w, "home", m)
	})

	// Serve the embedded static assets the renderer's SRI tags point at.
	static := middleware.ConfigureStaticAssets(true)
	r.PathPrefix("/static/").Handler(static(http.FileServerFS(assets)))

	srv, err := server.New("8080")
	if err != nil {
		panic(err)
	}
	_ = srv.ServeHTTPHandler(ctx, r)
}

See the getting-started guide for the full picture, including the recommended middleware chain.

Packages

Web layer

Package	Purpose
render	html/text template renderer with a rich FuncMap and SRI asset tags
middleware	Composable gorilla/mux middleware + the Authenticator seam
form	SSR form binding + validation (form/validate tags) for the parse → validate → re-render loop
session · flash · cookiestore	Typed session accessors, one-shot flash messages, hot-reloadable cookie store
webctx · response	Request-scoped context helpers and HTTP response/error helpers
i18n	gettext (.po) translations with Accept-Language matching

Infrastructure layer

Package	Purpose
server	Gracefully-stoppable HTTP server
secrets · keys	Pluggable secret/key managers (filesystem + in-memory core; cloud opt-in)
cache	Generic, TTL-based in-memory cache
logging	Context-scoped log/slog logger + logging.Config (LOG_LEVEL/LOG_MODE)

Opt-in cloud providers

The core secrets and keys packages have no cloud dependencies. Cloud providers are self-registering sub-packages you blank-import, so their SDKs are only linked when used:

import _ "github.com/mikehelmick/go-bananas/secrets/gcp"   // or aws, azure, vault
import _ "github.com/mikehelmick/go-bananas/keys/gcp"      // or aws, azure, vault

Configuration

There is no config package. Packages that need settings expose an env-tagged Config struct (logging.Config, secrets.Config, keys.Config); an app composes them into its own config and processes everything once with go-envconfig:

type appConfig struct {
	Logging logging.Config // LOG_LEVEL, LOG_MODE
	Secrets secrets.Config

	DevMode bool   `env:"DEV_MODE, default=false"`
	Port    string `env:"PORT, default=8080"`
}

var cfg appConfig
if err := envconfig.Process(ctx, &cfg); err != nil { /* handle */ }
logger := logging.NewLoggerFromConfig(cfg.Logging)

Claude Code skills

This repo ships Claude Code skills that help developers and agents build go-bananas apps (scaffolding, the middleware chain, authentication, and secrets/keys). Install them via the plugin marketplace:

/plugin marketplace add mikehelmick/go-bananas

Contributing

Issues and pull requests are welcome. Run make test and make lint before submitting.

License

Apache 2.0 — see LICENSE. Significant portions are extracted from the Exposure Notifications projects (Google LLC), also Apache 2.0.

Documentation

Overview

Package gobananas is the documentation root for go-bananas, the application framework for Go that is so simple, it's Bananas.

go-bananas is a lean, server-side-rendered (SSR) web framework plus a small application-infrastructure layer. It is assembled from focused, composable packages rather than a single monolith, so you import only what you need.

Web layer

• github.com/mikehelmick/go-bananas/render: an html/template + text/template renderer with a rich default FuncMap, Subresource Integrity (SRI) asset tags, and optional hot-reload in development.
• github.com/mikehelmick/go-bananas/middleware: composable gorilla/mux middleware (secure headers, CSRF, sessions, gzip, request/trace IDs, locale, and a pluggable Authenticator seam).
• github.com/mikehelmick/go-bananas/session, github.com/mikehelmick/go-bananas/flash, and github.com/mikehelmick/go-bananas/cookiestore: typed session accessors, one-shot flash messages, and a hot-reloadable secure-cookie store.
• github.com/mikehelmick/go-bananas/webctx and github.com/mikehelmick/go-bananas/response: request-scoped context helpers and HTTP response/error helpers.

Infrastructure layer

• github.com/mikehelmick/go-bananas/server: a gracefully-stoppable HTTP server.
• github.com/mikehelmick/go-bananas/secrets and github.com/mikehelmick/go-bananas/keys: pluggable secret and key managers. The core ships filesystem and in-memory providers; cloud providers (GCP, AWS, Azure, Vault) are opt-in sub-packages you blank-import to self-register, so their SDKs are only linked when used.
• github.com/mikehelmick/go-bananas/cache: a generic, TTL-based in-memory cache.
• github.com/mikehelmick/go-bananas/logging: a context-scoped log/slog-based logger.

See the example application under examples/ssr-oidc for an end-to-end SSR app wiring these packages together, including an OIDC Authenticator.