Agent Skills: Configuration Skill

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

| Rule | Detail | | ----------------- | ---------------------------------------------- | | PUBLIC__ prefix | Exposed to browser (client-safe) | | No prefix | Server-only (secrets) | | __ separator | Navigate nested paths | | Auto-parsing | Numbers, booleans, JSON parsed automatically | | Validation | Paths must exist in config.server.ts | | Depth limit | Maximum 10 levels | | MRT limits | Names max 512 chars; total PUBLIC__ max 32KB |

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

| Pitfall | Problem | Solution | | ----------------- | ------------------------------------------ | -------------------------------------------------- | | Missing context | getConfig() returns undefined in loaders | Use getConfig(context) on server | | Typo in env var | Variable silently ignored | Validation catches paths not in config.server.ts | | Exposing secrets | Sensitive data in browser | Use no-prefix variables; access via process.env |

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