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:

1import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";
2
3const { clientId, siteId } = getConfig().app.commerceAPI.parameters;

Storefront Next:

1import { getConfig } from "@/config";
2
3// In a loader
4export function loader({ context }: LoaderFunctionArgs) {
5  const { clientId, siteId } = getConfig(context).commerce.api;
6}
7
8// In a component
9function MyComponent() {
10  const { clientId, siteId } = useConfig().commerce.api;
11}

Example: Feature Flag Check

PWA Kit:

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

Storefront Next:

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

Key Differences

Type Safety: Storefront Next provides full TypeScript type definitions, while PWA Kit uses plain JavaScript with no type checking.
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.
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.
React Integration: Storefront Next requires using useConfig() hook in React components (proper React Context pattern), while PWA Kit allows calling getConfig() anywhere.
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.
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):

1import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";
2
3function ProductDetail() {
4  const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? true;
5  const { clientId } = getConfig().app.commerceAPI.parameters;
6  // ...
7}

After (Storefront Next):

1import { useConfig } from "@/config";
2
3function ProductDetail() {
4  const config = useConfig();
5  const { clientId } = config.commerce.api;
6  // storeLocatorEnabled is now in extension config
7  // ...
8}

Environment Variables

Before (PWA Kit):

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

After (Storefront Next):

1# Required Commerce API credentials
2PUBLIC__app__commerce__api__clientId=your-client-id
3PUBLIC__app__commerce__api__organizationId=your-org-id
4PUBLIC__app__commerce__api__siteId=your-site-id
5PUBLIC__app__commerce__api__shortCode=your-short-code
6
7# Optional feature toggles
8PUBLIC__app__site__features__socialLogin__enabled=true
9PUBLIC__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:

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