chi: Lightweight Routing & Middleware

chi adds method-aware routing, URL parameters, and middleware composition on top of net/http without introducing a custom handler type.

Handlers stay func(http.ResponseWriter, *http.Request), so chi fits teams that want router ergonomics with stdlib portability.

Summary

chi builds a radix tree of routes at registration time and dispatches incoming requests through a middleware stack before your handler runs.

Route groups (Route, Group, Mount) let you scope middleware and prefixes to subtrees.

Because chi.Router implements http.Handler, you drop it into http.Server, integration tests, and reverse proxies the same way you would a plain ServeMux.

Recipe

Quick-reference recipe card - copy-paste ready.

r := chi.NewRouter()
r.Use(middleware.RequestID, middleware.Recoverer)
 
r.Route("/api", func(r chi.Router) {
    r.Get("/users/{id}", getUser)
})
 
http.ListenAndServe(":8080", r)

When to reach for this:

• REST APIs that need grouped routes and middleware without framework lock-in
• Services that must compose with stdlib http.Handler middleware (OTel, auth gateways)
• Libraries exposing an http.Handler for consumers to mount
• Incremental migration off http.ServeMux while keeping existing handlers

Working Example

package main
 
import (
    "encoding/json"
    "net/http"
    "strconv"
    "time"
 
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
)
 
type user struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}
 
var users = map[int]user{1: {ID: 1, Name: "Ada"}}
 
func getUser(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(chi.URLParam(r, "id"))
    if err != nil {
        http.Error(w, "invalid id", http.StatusBadRequest)
        return
    }
    u, ok := users[id]
    if !ok {
        http.Error(w, "not found", http.StatusNotFound)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(u)
}
 
func main() {
    r := chi.NewRouter()
    r.Use(middleware.RequestID)
    r.Use(middleware.RealIP)
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)
    r.Use(middleware.Timeout(30 * time.Second))
 
    r.Route("/api/v1", func(r chi.Router) {
        r.Get("/users/{id}", getUser)
        r.Post("/users", func(w http.ResponseWriter, r *http.Request) {
            var in user
            if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
                http.Error(w, err.Error(), http.StatusBadRequest)
                return
            }
            users[in.ID] = in
            w.WriteHeader(http.StatusCreated)
            json.NewEncoder(w).Encode(in)
        })
    })
 
    srv := &http.Server{Addr: ":8080", Handler: r}
    srv.ListenAndServe()
}

What this demonstrates:

• Middleware stack applied to all /api/v1 routes
• URL param parsing with validation before domain lookup
• JSON read/write without a framework context wrapper
• Production-oriented timeouts and panic recovery from chi middleware

Deep Dive

How It Works

• chi.NewRouter() allocates a route tree; each Get/Post registers a method + pattern node.
• Use wraps the current router's handler chain; sub-routers inherit parent middleware unless registered before a branch.
• Mount("/prefix", sub) strips the prefix and delegates matching to sub.
• Unmatched requests fall through to http.NotFound unless you set r.NotFound and r.MethodNotAllowed.

Route Patterns at a Glance

Middleware Ordering

Outer middleware runs first on the way in and last on the way out.

Register logging and recovery early; place auth after logging so rejected requests still leave an audit trail.

Timeout middleware should sit outside handlers that may block.

Go Notes

import "context"
 
// Custom middleware: attach a value to context, stdlib style
func withTenant(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        tenant := r.Header.Get("X-Tenant")
        type tenantKeyType struct{}
        ctx := context.WithValue(r.Context(), tenantKeyType{}, tenant)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Prefer typed context keys (custom int type) over bare strings to avoid collisions.

Gotchas

• Mount prefix stripping - Handlers on mounted routers see paths without the mount prefix; logging the raw r.URL.Path confuses operators. Fix: log chi.RouteContext(r).RoutePattern or include mount prefix in structured fields.
• Middleware on wrong router - Calling Use after Mount does not retroactively wrap mounted subtrees registered earlier. Fix: register shared Use on the parent before Mount, or add middleware on each sub-router.
• Param always string - chi.URLParam returns string; forgetting strconv produces silent 0 IDs. Fix: parse and validate before domain calls.
• Default Server timeouts - http.ListenAndServe uses zero timeouts; chi's Timeout middleware helps but does not replace ReadHeaderTimeout on http.Server. Fix: configure http.Server timeouts explicitly.
• Trailing slash redirects - chi can redirect /users to /users/ depending on registration; inconsistent clients may double-hit. Fix: pick one style and register both or disable redirects consciously.
• Global state in handlers - Examples use maps for brevity; production code needs injected stores. Fix: close over dependencies via handler constructors returning http.HandlerFunc.

Alternatives

FAQs

Related

• Web Frameworks Basics - chi hello routes and groups
• Go HTTP Frameworks: Routers vs Full Frameworks - router positioning
• gorilla/mux: Regex Routes & Host Matching - when mux patterns win
• Middleware & Decorator Patterns - middleware composition
• Middleware Chains & Request Context - context in middleware

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).