Configuration Skill

This skill covers the Storefront Next configuration system — centralized in config.server.ts with environment variable overrides.

Overview

All configuration is centralized in config.server.ts with typed defaults. Environment variables (via .env files or MRT settings) override these defaults. The system provides type-safe access with automatic parsing and validation.

Adding Configuration

1. Define the type in src/types/config.ts

export type Config = {
  app: {
    myFeature: {
      enabled: boolean;
      maxItems: number;
    };
  };
};

2. Set defaults in config.server.ts

export default defineConfig({
  app: {
    myFeature: {
      enabled: false,
      maxItems: 10,
    },
  },
});

3. Override via environment variables

PUBLIC__app__myFeature__enabled=true
PUBLIC__app__myFeature__maxItems=20

Accessing Configuration

In React Components

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

export function MyComponent() {
  const config = useConfig();

  if (config.myFeature.enabled) {
    const maxItems = config.myFeature.maxItems;
    // Feature code
  }
}

In Server Loaders/Actions

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

export function loader({context}: LoaderFunctionArgs) {
  const config = getConfig(context); // context is required on server

  if (config.myFeature.enabled) {
    // Loader code
  }
}

In Browser Code (Non-Route Modules)

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

export function getFeatureFlag() {
  const config = getConfig(); // No context needed in browser (uses window.__APP_CONFIG__)
  return config.myFeature.enabled;
}

Note: getConfig() and useConfig() return AppConfig — the app section of the full config. Access properties directly (e.g., config.myFeature.enabled) without the app prefix.

Environment Variable Rules

# Pattern: PUBLIC__app__{path}__{to}__{property}=value
PUBLIC__app__commerce__api__clientId=abc123
# Maps to config.app.commerce.api.clientId
# Accessed as config.commerce.api.clientId

Multi-Site Configuration

PUBLIC__app__commerce__sites='[
  {
    "id": "RefArchGlobal",
    "defaultLocale": "en-US",
    "defaultCurrency": "USD",
    "supportedLocales": [
      {"id": "en-US", "preferredCurrency": "USD"},
      {"id": "de-DE", "preferredCurrency": "EUR"}
    ],
    "supportedCurrencies": ["USD", "EUR"]
  }
]'

const config = getConfig(context);
const currentSite = config.commerce.sites[0];
const locale = currentSite.defaultLocale; // "en-US"
const currency = currentSite.defaultCurrency; // "USD"

Security

# Client-safe (PUBLIC__ prefix)
PUBLIC__app__commerce__api__clientId=abc123

# Server-only (no prefix — never sent to client)
COMMERCE_API_SLAS_SECRET=your-secret

Read server-only secrets directly from process.env — never add them to the config system.

Common Pitfalls

Related Skills

• storefront-next:sfnext-project-setup - Initial environment setup and .env configuration
• storefront-next:sfnext-data-fetching - Using config in loader functions
• storefront-next:sfnext-deployment - MRT environment variable configuration