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
| Area | Location |
|---|---|
| env schema (kit keys) | apps/web/config/kit-env.ts |
| env schema (your keys) | apps/web/env.ts |
| local env template | apps/web/env.example |
| app settings | apps/web/config/app.config.server.ts |
| auth settings | apps/web/config/auth.config.server.ts |
| account mode | apps/web/config/account-mode.config.server.ts |
| feature flags | apps/web/config/feature-flags.config.server.ts |
| what the browser sees | apps/web/config/public-config.server.ts |
| app navigation | apps/web/config/navigation.config.tsx |
| settings pages | apps/web/config/settings-navigation.config.tsx |
| theme tokens | apps/web/styles/theme.css |
| error pages | apps/web/pages/[...slug].tsx, apps/web/public/500.html |
| security (CSP origins, webhook paths) | apps/web/config/security.config.ts |
| locales and default locale | apps/web/config/i18n.config.ts |
| your translation messages | apps/web/messages/<locale>/<namespace>.json |
How Configuration Flows
apps/web/env.tsdeclares every variable (defineEnvfromvoid/env). Values are validated atvoid env check, atvoid secret putand when the Worker starts. An invalid value stops the app; it never falls back silently.- Server code reads typed config through getters:
getAppConfig(),getAuthConfig(),getFeatureFlags(),getAccountMode(). Only*.server.tsfiles and handlers call them. middleware/01.config.tsputs a public projection,getPublicConfig(), into Void's shared data. Components read it withuseShared().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 (
.envlocally,void secret putwhen deployed). - Add a value: declare it in
apps/web/env.tsand 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.tsx | apps/web/middleware/00.errors.ts, 01.config.ts, 02.theme.ts |
apps/web/styles/theme.css, custom.css | apps/web/styles/shadcn-ui.css, makerkit.css |
apps/web/public/500.html | apps/web/pages/[...slug].*, apps/web/routes/api/[...path].ts |
apps/web/components/error-page-content.tsx | apps/web/types/shared.ts, packages/* |
apps/web/config/security.config.ts | apps/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
- App Configuration
- Environment Variables
- Account Modes
- Feature Flags
- Navigation
- Theme and Layout
- 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 →