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/.env
PRODUCT_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, dark or system (DEFAULT_THEME_MODE)
  • production: true in 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_FACTOR
  • providers.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 into public-config.server.ts (OAuth Sign-In)
  • passwordRequirements.specialChars, .numbers, .uppercase: PASSWORD_REQUIRE_*
  • displayTermsCheckbox: DISPLAY_TERMS_AND_CONDITIONS_CHECKBOX
  • turnstile: { siteKey, secretKey } from TURNSTILE_SITE_KEY + TURNSTILE_SECRET_KEY when both are set, server-only; the public config gets captchaSiteKey alone (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.ts
import { 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, defaultTheme
  • auth: providers, passwordRequirements, displayTermsCheckbox, captchaSiteKey
  • flags: 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_URL must use https, except on localhost or 127.0.0.1. Each deployed Worker sets its own.
  • APP_HOME_PATH must start with /.
  • Changing the home path doesn't update redirects you hard-coded elsewhere; read appHomePath instead.
  • Importing a *.config.server.ts file into a component fails the build. Use useShared().config.
  • c.set('shared', { config }) without the spread drops other middleware's data.

Next: Environment Variables →