sfnext-configuration

Storefront Next Configuration

All app settings live in one typed file, config.server.ts. Environment variables override its values per environment; defineConfig() deep-merges them at startup. Full references ship in the project: docs/README-CONFIG.md (required/optional variable tables) and docs/README-CONFIG-OPTIONS.md (every option).

Model

config.server.ts default-exports defineConfig<Config>({ metadata, runtime, app }, { protectedPaths }), imported from @salesforce/storefront-next-runtime/config.

Section	Visible to	Contents
app	Server and browser (window.__APP_CONFIG__)	Commerce API, sites, features, URL/SEO routes, images, security, engagement
runtime	Server only	MRT settings such as ssrParameters (ssrFunctionNodeVersion, envBasePath), ssrOnly, ssrShared
metadata	Server only	Project name/slug

Because app reaches the browser, never put secrets in it.

Add a config value

1. Add the field to AppConfig in src/types/config.ts (Config = BaseConfig<AppConfig>; the AppConfigShape / ClientFacingAppConfigShape augmentations in that file give getConfig and useConfig their types).
2. Set a default under app in config.server.ts. Define the key even if the default is empty ('', []); env overrides are only accepted for paths that exist here.
3. Override per environment: PUBLIC__app__myFeature__enabled=true.
4. Run pnpm typecheck.

// src/types/config.ts (inside AppConfig)
myFeature: { enabled: boolean; maxItems: number };

// config.server.ts (inside app)
myFeature: { enabled: false, maxItems: 10 },

Read config

import { getConfig, useConfig } from '@salesforce/storefront-next-runtime/config';

// Loaders, actions, middleware (server): context is REQUIRED
export function loader({ context }: LoaderFunctionArgs) {
  const config = getConfig(context);      // full AppConfig incl. serverExtension
  return { max: config.myFeature.maxItems };
}

// Components
const config = useConfig();               // client-facing shape (no serverExtension)