Salesforce Docs Portal

Project Configuration Differences with PWA Kit

PWA Kit uses JavaScript configuration with looser runtime validation and flatter structures. Storefront Next introduces typed config definitions, structured namespaces, and an environment-variable override model designed for safer server-client separation. Access patterns also become more context-aware on the server and hook-based in React components.

Configuration Definition

Aspect PWA Kit Storefront Next
Language JavaScript TypeScript
Type Safety None (runtime) Full type definitions
Location config/default.js config.server.ts
Helper Function None defineConfig() for IDE autocomplete
Multi-site Config Separate sites.js file Simplified (single locale and currency)

Environment Variable Support

Aspect PWA Kit Storefront Next
Override System Limited (specific vars only) Full path-based override system
Naming Convention Custom per variable PUBLIC__path__to__config
JSON Parsing Manual Automatic
Validation None Strict schema validation
Client Exposure N/A PUBLIC__ prefix = client-safe

Accessing Configuration

Aspect PWA Kit Storefront Next
Server Access getConfig() getConfig(context)
Client Access getConfig() getConfig() or useConfig()
React Components getConfig() useConfig() hook required
Type Inference None Full TypeScript types
Context Required No Yes (server-side)

Configuration Scope

Feature PWA Kit Storefront Next
Commerce API app.commerceAPI.parameters app.commerce.api
Feature Flags Top-level booleans app.site.features namespace
Analytics app.einsteinAPI, app.dataCloudAPI app.engagement.adapters
UI Settings N/A app.pages, app.global
Performance N/A app.performance
i18n In sites.js app.i18n

Example: Accessing Commerce API Config

PWA Kit:

import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";

const { clientId, siteId } = getConfig().app.commerceAPI.parameters;

Storefront Next:

import { getConfig } from "@/config";

// In a loader
export function loader({ context }: LoaderFunctionArgs) {
  const { clientId, siteId } = getConfig(context).commerce.api;
}

// In a component
function MyComponent() {
  const { clientId, siteId } = useConfig().commerce.api;
}

Example: Feature Flag Check

PWA Kit:

const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? true;
const { passwordless = {} } = getConfig().app.login || {};

Storefront Next:

const config = useConfig();
const passwordlessEnabled = config.site.features.passwordlessLogin.enabled;
const socialLoginProviders = config.site.features.socialLogin.providers;

Key Differences

  1. Type Safety: Storefront Next provides full TypeScript type definitions, while PWA Kit uses plain JavaScript with no type checking.

  2. Environment Variables: Storefront Next has a sophisticated environment variable override system with validation, while PWA Kit relies on hardcoded values or manually-implemented env var handling.

  3. Context Requirement: Storefront Next requires passing router context to access config in server-side code, enabling proper isolation between requests. PWA Kit uses a global singleton.

  4. React Integration: Storefront Next requires using useConfig() hook in React components (proper React Context pattern), while PWA Kit allows calling getConfig() anywhere.

  5. Configuration Scope: Storefront Next organizes configuration into clear namespaces (pages, commerce, site, global, performance, engagement), while PWA Kit uses a flatter structure with mixed concerns.

  6. Multi-Site: PWA Kit has built-in multi-site configuration in sites.js with complex locale and currency mappings. Storefront Next simplifies this with single locale and currency values. Multi-site can be handled differently.

Storefront Conversion Considerations

Configuration File Changes

PWA Kit Storefront Next
config/default.js config.server.ts
config/sites.js Locale and currency in app.site
app.commerceAPI.parameters.clientId app.commerce.api.clientId
app.storeLocatorEnabled Move to extension config
app.multishipEnabled Move to extension config

Code Conversion

Before (PWA Kit):

import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";

function ProductDetail() {
  const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? true;
  const { clientId } = getConfig().app.commerceAPI.parameters;
  // ...
}

After (Storefront Next):

import { useConfig } from "@/config";

function ProductDetail() {
  const config = useConfig();
  const { clientId } = config.commerce.api;
  // storeLocatorEnabled is now in extension config
  // ...
}

Environment Variables

Before (PWA Kit):

# Limited environment variable support
# Most values hardcoded in config/default.js

After (Storefront Next):

# Required Commerce API credentials
PUBLIC__app__commerce__api__clientId=your-client-id
PUBLIC__app__commerce__api__organizationId=your-org-id
PUBLIC__app__commerce__api__siteId=your-site-id
PUBLIC__app__commerce__api__shortCode=your-short-code

# Optional feature toggles
PUBLIC__app__site__features__socialLogin__enabled=true
PUBLIC__app__pages__cart__maxQuantityPerItem=10

Server-Only Secrets

In Storefront Next, server-only secrets (like SLAS private key) should NOT use the PUBLIC__ config system:

// In server-side code only
const slasSecret = process.env.COMMERCE_API_SLAS_SECRET;