App Configuration Settings
Core app and auth settings, and how to read configuration on the server and in the browser.
Core settings come from environment variables and are read through typed getters in apps/web/config/.
This page is part of the Configuration documentation.
App Settings
# apps/web/.envPRODUCT_NAME="Your SaaS"SITE_URL="http://localhost:5173"DEFAULT_THEME_MODE="light"APP_HOME_PATH="/dashboard"getAppConfig() returns:
name: product name used in metadata and UI (PRODUCT_NAME)url: canonical site URL, used where there is no request (emails, jobs) (SITE_URL)theme: default theme mode,light,darkorsystem(DEFAULT_THEME_MODE)production:truein production builds (from Vite, not env)appHomePath: default authenticated landing path (APP_HOME_PATH)
Auth Settings
getAuthConfig() returns which sign-in methods are enabled and the password rules. The auth pages read them (Authentication).
providers.password,providers.magicLink,providers.emailOtp,providers.passkey,providers.twoFactor:AUTH_PASSWORD,AUTH_MAGIC_LINK,AUTH_EMAIL_OTP,AUTH_PASSKEY,AUTH_TWO_FACTORproviders.oAuth: the buttons of the OAuth providers with credentials,{ id, name?, logo? }from their entries, e.g.[{ id: 'google' }](public: no keys)oAuthProviders: those providers' credentials, server-only: never copy them intopublic-config.server.ts(OAuth Sign-In)passwordRequirements.specialChars,.numbers,.uppercase:PASSWORD_REQUIRE_*displayTermsCheckbox:DISPLAY_TERMS_AND_CONDITIONS_CHECKBOXturnstile:{ siteKey, secretKey }fromTURNSTILE_SITE_KEY+TURNSTILE_SECRET_KEYwhen both are set, server-only; the public config getscaptchaSiteKeyalone (Bot Protection)
Reading Configuration on the Server
Call the getters in loaders, actions, handlers and services (*.server.ts):
// apps/web/pages/(app)/dashboard/index.server.tsimport { defineHandler } from 'void';import { getAppConfig } from '#/config/app.config.server.ts';import { getFeatureFlags } from '#/config/feature-flags.config.server.ts';export const loader = defineHandler(async () => { const { name } = getAppConfig(); const { enableOrganizations } = getFeatureFlags(); return { name, enableOrganizations };});Getters read env on first use and keep the result for the life of the Worker isolate. They never read env at module top level.
Reading Configuration in the Browser
Components can't import the server getters: Void's build fails if client code reads a server env value. Use the public projection from shared data instead:
import { useShared } from '@void/react';export function ProductName() { const { config } = useShared(); return <span>{config.productName}</span>;}useShared().config (type PublicConfig) contains:
productName,siteUrl,appHomePath,defaultThemeauth:providers,passwordRequirements,displayTermsCheckbox,captchaSiteKeyflags: every feature flag (see Feature Flags)
Everything in it is sent to every visitor. apps/web/config/public-config.server.ts lists app and auth fields one by one; add a field there only if it is safe for anyone to see.
Adding Your Own Shared Data
useShared() is typed by the SharedData interface in apps/web/types/shared.ts.
Keep @void/md in the root dev dependencies. It supplies Void's optional peer across the workspace, so pnpm shares one Void instance between the app and @kit/i18n. Separate instances break SharedData augmentation and make useShared() return unknown.
Add a field from your own middleware file; never edit the kit's middleware:
// apps/web/middleware/20.announcement.ts (a number after the kit's, so it runs last)import { defineMiddleware } from 'void';declare module '../types/shared' { interface SharedData { announcement: string | null; }}export default defineMiddleware(async (c, next) => { c.set('shared', { ...c.get('shared'), announcement: null }); await next();});Always spread the existing value: other middleware has already put data there.
Common Pitfalls
SITE_URLmust use https, except onlocalhostor127.0.0.1. Each deployed Worker sets its own.APP_HOME_PATHmust start with/.- Changing the home path doesn't update redirects you hard-coded elsewhere; read
appHomePathinstead. - Importing a
*.config.server.tsfile into a component fails the build. UseuseShared().config. c.set('shared', { config })without the spread drops other middleware's data.
Next: Environment Variables →