sfnext-configuration

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.