Settings
A Ghuri project is configured by one file, src/settings.ts, whose default export is created
with defineSettings(). Keys keep Django’s UPPER_SNAKE names, so INSTALLED_APPS,
MIDDLEWARE, DATABASES and friends mean what you expect.
import { defineSettings, SecurityMiddleware, CommonMiddleware, CsrfMiddleware, kvCache, memoryCache } from '@ghuri/core'import { d1, postgres } from '@ghuri/orm'import { r2 } from '@ghuri/storage'import { ContentTypesConfig, AuthConfig, SessionsConfig, SessionMiddleware, AuthenticationMiddleware,} from '@ghuri/auth'import { AdminConfig } from '@ghuri/admin'import { BlogConfig } from './blog/app'import { urlpatterns } from './urls'
export default defineSettings((env) => ({ SECRET_KEY: env.SECRET_KEY, DEBUG: env.DEBUG === 'true', ALLOWED_HOSTS: ['blog.example.com', 'localhost'], INSTALLED_APPS: [ContentTypesConfig, AuthConfig, SessionsConfig, AdminConfig, BlogConfig], MIDDLEWARE: [SecurityMiddleware, SessionMiddleware, CommonMiddleware, CsrfMiddleware, AuthenticationMiddleware], ROOT_URLCONF: urlpatterns, DATABASES: { default: env.DATABASE_URL ? postgres({ url: env.DATABASE_URL }) : d1('DB'), }, STORAGES: { default: r2('MEDIA', { publicUrl: 'https://media.example.com' }) }, CACHES: { default: env.CACHE ? kvCache('CACHE') : memoryCache() }, TIME_ZONE: 'UTC',}))Settings are a function of env
Section titled “Settings are a function of env”In Django, settings.py runs once at import time and reads os.environ. A Cloudflare Worker
has no process environment: secrets, variables and resource bindings (D1, R2, KV) arrive as an
env object passed to every request. So defineSettings() takes a function of env rather
than an object.
- On Workers,
envis the Worker’s environment:varsfromwrangler.jsonc, secrets set withwrangler secret put, and bindings. Locally,.dev.varsfills in secrets. - On Node,
envis whatever you pass toserve()from@ghuri/core/node, normallyprocess.env(the default). - In the CLI,
envis built fromwrangler.jsoncbindings (local, or remote with--remote) merged with.env/.dev.varsandprocess.env.
The function runs once per distinct env object. The result is cached in a WeakMap, merged
over the defaults, and validated, so calling it is cheap and you can treat settings as constants
after startup. Because env values are always strings on Workers, convert explicitly:
DEBUG: env.DEBUG === 'true', PAGE_SIZE: Number(env.PAGE_SIZE ?? 20).
createApp() also accepts a plain function or a settings object and wraps it with
defineSettings() for you, but exporting a defineSettings() factory is what the CLI expects.
Adapters such as d1('DB'), r2('MEDIA') and kvCache('CACHE') take a binding name, not
a binding. They look the binding up on env when the first connection is made. That keeps
settings.ts free of runtime objects and is what lets the same file describe both a Worker and
a Node process.
Reading settings at runtime
Section titled “Reading settings at runtime”Anywhere code runs inside a request (or a CLI command, or a test after app.setup()), read the
active settings with getSettings():
import { getSettings, setting } from '@ghuri/core'
const debug = getSettings().DEBUGconst pageSize = setting('PAGE_SIZE', 20) // with a fallback for unset keysBoth read from the current request context. Calling them at module top
level, before any request, throws ImproperlyConfigured. That is deliberate: on Workers there
is no env until the first request arrives.
Inside middleware or an error handler that has the Hono context, settingsFor(c) returns the
request’s settings (or undefined) without throwing, even when the code runs outside the
AsyncLocalStorage scope.
To reach a raw binding (for example a Workers AI binding that no Ghuri adapter wraps), use
getEnv():
import { getEnv } from '@ghuri/core'
const answer = await getEnv().AI.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', { prompt })Prefer adapters where they exist. Code that touches env.DB directly will not survive a move
to Postgres.
The request context
Section titled “The request context”Settings, database connections, the current user and other per-request state live in a
GhuriContext carried by AsyncLocalStorage (which is why nodejs_compat is required).
createApp() wraps every request, cron trigger and queue batch in runWithContext(). Outside
those, the CLI and test helpers call app.setup(env), which populates apps and installs a
global fallback context.
interface GhuriContext { env: Env settings: GhuriSettings executionCtx?: { waitUntil(p: Promise<unknown>): void; passThroughOnException?(): void } request?: Request hono?: import('hono').Context state: Map<string | symbol, unknown> // per-request cache}getContext() returns it (and throws outside one); tryGetContext() returns undefined
instead. The Hono context carries it too, as c.get('ghuri'). To run code with a context of
your own, for example in a script, build one with createContext({ env, settings }) and call
runWithContext(ctx, fn).
You rarely need it directly, but getContext().executionCtx?.waitUntil(promise) is the way to
run work after the response is sent on Workers. On Node, serve() provides a waitUntil shim
that tracks the promises and drains them on shutdown.
Package settings and type safety
Section titled “Package settings and type safety”GhuriSettings is an interface that each package extends with declaration merging. Installing
@ghuri/orm makes DATABASES a known, typed key; @ghuri/rest adds REST_FRAMEWORK, and so
on. You can do the same for your own settings:
declare module '@ghuri/core' { interface GhuriSettings { BLOG_POSTS_PER_FEED?: number }}const perFeed = setting('BLOG_POSTS_PER_FEED', 20)Unknown keys are allowed (the interface has an index signature), but declaring them gives you autocompletion and catches typos.
Validation and checks
Section titled “Validation and checks”When settings are first resolved, Ghuri checks the basics: SECRET_KEY must be set unless
DEBUG is on, and INSTALLED_APPS and ROOT_URLCONF must be arrays. Then the
system check framework takes over:
core checks URL patterns and MIDDLEWARE entries, and packages register their own (for example,
@ghuri/auth checks that AUTH_USER_MODEL names an installed model). Run them with:
npx ghuri checknpx ghuri check --deploy # adds Django's security warnings (DEBUG, SECRET_KEY, HSTS, CSRF cookie…)When DEBUG is on, checks also run at startup; an error stops the app with a clear message
(pass createApp(settings, { checks: false }) to skip them). Silence messages by id with
SILENCED_SYSTEM_CHECKS: ['security.W004'].
Register your own checks with checks.register(), typically from an AppConfig.ready():
import { checks } from '@ghuri/core'
checks.register(({ settings }) => settings.BLOG_POSTS_PER_FEED === 0 ? [checks.error('BLOG_POSTS_PER_FEED must be positive.', { id: 'blog.E001' })] : [], { tags: ['blog'] }, // { deploy: true } for deploy-only checks)runChecks({ deploy?, tags? }) runs them programmatically and returns CheckMessages.
Core settings
Section titled “Core settings”| Setting | Default | Meaning |
|---|---|---|
SECRET_KEY |
required | Signs sessions, CSRF tokens, password reset tokens. Optional only with DEBUG. |
DEBUG |
false |
Detailed error pages with stack traces; runs checks at startup. Never in production. |
ALLOWED_HOSTS |
['*'] |
Host header values the site will serve. Enforced by the app itself on every request (400 DisallowedHost). An empty list with DEBUG allows localhost only. |
INSTALLED_APPS |
required | AppConfig classes or instances, in order. |
MIDDLEWARE |
[] |
Middleware classes, configured instances, or Hono middleware handlers, outermost first. |
ROOT_URLCONF |
required | The root URL pattern array. |
APPEND_SLASH |
true |
Redirect GET /x to /x/ when only the latter matches. |
TIME_ZONE / USE_TZ |
'UTC' / true |
Time zone for display (the admin uses TIME_ZONE). |
CACHES |
memory cache | Cache aliases. See Caching. |
CSRF_TRUSTED_ORIGINS |
[] |
Extra origins allowed for unsafe requests. |
CORS |
false |
{ allowOrigins, allowCredentials, … } for CorsMiddleware. |
API_PATH_PREFIXES |
['/api'] |
Errors under these paths are always rendered as JSON. |
Security, CSRF and host settings (SECURE_*, CSRF_COOKIE_*, X_FRAME_OPTIONS,
USE_X_FORWARDED_HOST, PREPEND_WWW, …) and every setting from every other package are listed
in the settings reference.