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.

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)

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

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)

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`

PWA Kit:

Storefront Next:

PWA Kit:

Storefront Next:

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.

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

Before (PWA Kit):

After (Storefront Next):

Before (PWA Kit):

After (Storefront Next):

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