Configuration

AppConfig frozen dataclass and all configuration options

2 min read 333 words

AppConfig

Chirp uses a frozen dataclass for configuration. Every field has IDE autocomplete, type checking, and no runtimeKeyErrorsurprises.

from chirp import App, AppConfig

config = AppConfig(
    debug=True,
    host="0.0.0.0",
    port=8000,
    secret_key="change-me-in-production",
    template_dir="templates/",
)

app = App(config=config)

AppConfig is @dataclass(frozen=True, slots=True). Once created, it cannot be mutated. This is intentional -- config should not change after the app starts.

Configuration Fields

Field Type Default Description
debug bool False Enable debug mode (verbose errors, template auto-reload)
host str "127.0.0.1" Bind address for the development server
port int 8000 Bind port for the development server
secret_key str | None None Secret key for session signing (required for sessions)
template_dir str "templates" Directory for kida templates
static_dir str | None None Directory for static files (if using StaticFiles middleware)
static_url str "/static" URL prefix for static files

Debug Mode

Whendebug=True:

  • Detailed error pages with tracebacks are shown in the browser
  • Templates auto-reload when modified (no server restart needed)
  • Stricter validation warnings are surfaced
config = AppConfig(debug=True)

Warning

Never enable debug mode in production. It exposes internal details including source code and tracebacks.

Secret Key

Required for session middleware and CSRF protection. Use a strong random value in production:

import secrets

config = AppConfig(
    secret_key=secrets.token_hex(32),
)

Note

If you useSessionMiddleware or CSRFMiddleware without setting a secret_key, Chirp raises a ConfigurationErrorat startup.

Default Configuration

If you don't pass a config, sensible defaults are used:

app = App()  # Uses default AppConfig

This is equivalent to:

app = App(config=AppConfig())

Next Steps