THIS IS A MAJOR RELEASE WITH BREAKING CHANGES

READ THIS UPGRADE GUIDE BEFORE USING IT
UPGRADE SUPPORT IS AVAILABLE HERE

This release introduces v4 - a ground-up rewrite of error-pages. All external dependencies have been removed, and the project now runs entirely on the Go standard library.

Breaking changes

• Two separate binaries replace the old serve / build / healthcheck subcommands:
  • error-pages - HTTP server (dynamic rendering)
  • builder - static generator that pre-renders {code}.{html,json,xml,txt} to disk
• Environment variables were renamed: TEMPLATES_ROTATION_MODE -> ROTATION_MODE, RESPONSE_JSON_FORMAT -> JSON_TEMPLATE, and more.
• --add-code separator changed from / to |; multiple entries now use ||
• Many CLI flags and environment variables have been renamed
• Template fields were renamed: {{ code }} -> {{ .StatusCode }} (v3 syntax is still automatically rewritten at parse time through a shim, but it is deprecated)
• Other changes are described here

What's new

HTTP server

• FastHTTP has been replaced with the standard library net/http; HTTP/1.1 and HTTP/2 h2c are served on the same listener, with no TLS required.
• Gzip compression is now available for all response formats (HTML, JSON, XML, and plain text) when Accept-Encoding: gzip is set.
• HTML minification has been removed, since gzip gives similar savings with less complexity.
• Format negotiation now follows this order: URL extension -> Content-Type -> X-Format -> Accept header (highest q-value wins).

Template engine

• New internal/template package with a clean Data / Config split - templates are parsed once at startup.
• 48 built-in template functions: now, hostname, env (with secret masking), toJson, escape, l10nScript, and many more.
• The v3 -> v4 token shim automatically rewrites old syntax at parse time.
• Custom template loader (tploader): HTTP/HTTPS URL, file path, or inline literal - loaded concurrently at startup.

Localization

l10n/locales.json is now the single source of truth (15+ languages).

Helm chart

A new deploy/helm/ directory includes Chart.yaml, values.yaml, values.schema.json, and deployment, service, and middleware templates. Check the artifacthub for more details.

CLI "framework"

A custom internal/cli package provides a generic Flag[T] implementation with no external dependencies, and value precedence is now: default -> env var -> CLI flag.

Documentation

• Detailed migration guide
• CLI reference
• Data struct field reference and all template functions with examples
• Integration recipes for nginx, Traefik, Caddy, Kubernetes (nginx-ingress, NGF, Envoy, HAProxy, Traefik), and more

🐋 Docker images

// server
ghcr.io/tarampampam/error-pages:4.0.0
ghcr.io/tarampampam/error-pages:4.0
ghcr.io/tarampampam/error-pages:4
quay.io/tarampampam/error-pages:4.0.0
quay.io/tarampampam/error-pages:4.0
quay.io/tarampampam/error-pages:4
tarampampam/error-pages:4.0.0
tarampampam/error-pages:4.0
tarampampam/error-pages:4

// builder
ghcr.io/tarampampam/error-pages:4.0.0-builder
ghcr.io/tarampampam/error-pages:4.0-builder
ghcr.io/tarampampam/error-pages:4-builder
quay.io/tarampampam/error-pages:4.0.0-builder
quay.io/tarampampam/error-pages:4.0-builder
quay.io/tarampampam/error-pages:4-builder
tarampampam/error-pages:4.0.0-builder
tarampampam/error-pages:4.0-builder
tarampampam/error-pages:4-builder

📦 Helm chart

helm install error-pages oci://ghcr.io/tarampampam/error-pages/charts/error-pages \
  --version 4.0.0