Application Configuration

Where app configuration lives, how it reaches the server and the browser, and which files are yours to edit.

Almost everything is configured through environment variables declared in one typed schema. The server reads them through small config getters; the browser gets a public copy through Void's shared data. You rarely need to edit code to change behaviour.

Main Locations

AreaLocation
env schema (kit keys)apps/web/config/kit-env.ts
env schema (your keys)apps/web/env.ts
local env templateapps/web/env.example
app settingsapps/web/config/app.config.server.ts
auth settingsapps/web/config/auth.config.server.ts
account modeapps/web/config/account-mode.config.server.ts
feature flagsapps/web/config/feature-flags.config.server.ts
what the browser seesapps/web/config/public-config.server.ts
app navigationapps/web/config/navigation.config.tsx
settings pagesapps/web/config/settings-navigation.config.tsx
theme tokensapps/web/styles/theme.css
error pagesapps/web/pages/[...slug].tsx, apps/web/public/500.html
security (CSP origins, webhook paths)apps/web/config/security.config.ts
locales and default localeapps/web/config/i18n.config.ts
your translation messagesapps/web/messages/<locale>/<namespace>.json

How Configuration Flows

  1. apps/web/env.ts declares every variable (defineEnv from void/env). Values are validated at void env check, at void secret put and when the Worker starts. An invalid value stops the app; it never falls back silently.
  2. Server code reads typed config through getters: getAppConfig(), getAuthConfig(), getFeatureFlags(), getAccountMode(). Only *.server.ts files and handlers call them.
  3. middleware/01.config.ts puts a public projection, getPublicConfig(), into Void's shared data. Components read it with useShared().config.

There are no VITE_* variables: the browser gets configuration at request time, so changing a value needs a new secret, not a rebuild.

How to Choose

  • Change a value per environment: set the env var (.env locally, void secret put when deployed).
  • Add a value: declare it in apps/web/env.ts and read it in a getter. See Environment Variables.
  • Change navigation, theme colors or error-page copy: edit the customer-owned files below.

Files You Own vs Files the Kit Owns

You will merge Makerkit updates into your fork. To keep those merges clean, the kit's own logic and your customizations live in different files.

Yours (edit freely; the kit rarely changes them)The kit's (avoid editing; updates land here)
apps/web/env.ts (your keys)apps/web/config/kit-env.ts
apps/web/config/navigation.config.tsx, settings-navigation.config.tsx, and the config files marked "Yours to edit" (billing, content, policies, hooks, cleanup, outbox)apps/web/config/kit-*.ts and the config files marked "Kit-owned" (the bindings to @kit/*: auth, billing, organizations, outbox, cleanup, emails, i18n messages)
apps/web/pages/layout.tsxapps/web/middleware/00.errors.ts, 01.config.ts, 02.theme.ts
apps/web/styles/theme.css, custom.cssapps/web/styles/shadcn-ui.css, makerkit.css
apps/web/public/500.htmlapps/web/pages/[...slug].*, apps/web/routes/api/[...path].ts
apps/web/components/error-page-content.tsxapps/web/types/shared.ts, packages/*
apps/web/config/security.config.tsapps/web/middleware/03.security.ts, 04.api-origin.ts, packages/security/src/types.ts
apps/web/config/i18n.config.ts, apps/web/messages/**packages/i18n/src/messages/**, apps/web/config/i18n.messages.ts, apps/web/lib/i18n.client.ts, apps/web/lib/i18n.server.ts, apps/web/middleware/05.locale.ts
apps/web/void.lock.json (once you've deployed; commit it).github/**, tooling/scripts/src/preview-env.mjs, the deploy and preview tasks in apps/web/vite.config.ts

Each file in apps/web/config/ says at the top who owns it. To change kit behaviour, prefer adding your own file (a new middleware, a wrapper component) over editing a kit file.

Topics

  1. App Configuration
  2. Environment Variables
  3. Account Modes
  4. Feature Flags
  5. Navigation
  6. Theme and Layout
  7. Error Pages

Security headers, the Content Security Policy and CSRF protection are covered in the Security documentation. Locales, messages and translations are covered in the Internationalization documentation. CI and production deploys to your Cloudflare account are covered in the Deployment documentation.


Next: App Configuration →