# 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:

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

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

Storefront Next:

```typescript
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:

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

Storefront Next:

```typescript
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):

```javascript
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):

```typescript
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):

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

After (Storefront Next):

```bash
# 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:

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