# App Configuration Settings

> Core app and auth settings, and how to read configuration on the server and in the browser.

*Canonical: https://makerkit.dev/docs/void-cloudflare/configuration/app-configuration*

---

Core settings come from environment variables and are read through typed getters in `apps/web/config/`.

This page is part of the [Configuration documentation](./overview).

## App Settings

```bash
# 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](../authentication/overview)).

- `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](../authentication/oauth))
- `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](../authentication/captcha))

## Reading Configuration on the Server

Call the getters in loaders, actions, handlers and services (`*.server.ts`):

```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:

```tsx
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](./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:

```ts
// 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 →](./environment-variables)
