@commercengine/storefront-sdk-nextjs 0.3.0 → 0.4.0

package/MIGRATION.md

@@ -1,89 +1,197 @@
 # Storefront SDK Next.js Migration Guide
 
-This guide covers the breaking API changes in
-`@commercengine/storefront-sdk-nextjs`.
+This package is now a **frozen legacy wrapper**. The supported migration target
+is:
 
-## Summary
+```bash
+pnpm add @commercengine/storefront
+```
+
+Then move your Next.js imports to:
 
-- `storefront()` was replaced by explicit `storefront.public()` and
-  `storefront.session(...)`
-- `isRootLayout` was removed
-- root layouts and public server reads now use `storefront.public()`
-- server-side session usage now always uses `storefront.session(await cookies())`
-- client-side session usage uses `storefront.session()`
+```typescript
+import { Environment } from "@commercengine/storefront";
+import {
+  createNextjsStorefront,
+  type NextjsStorefrontConfig,
+} from "@commercengine/storefront/nextjs";
+```
+
+## What Changes
+
+- package install changes from `@commercengine/storefront-sdk-nextjs` to
+  `@commercengine/storefront`
+- `createStorefront(...)` becomes `createNextjsStorefront(...)`
+- `storefront.public()` becomes `storefront.publicStorefront()`
+- `storefront.session()` becomes `storefront.clientStorefront()` in browser code
+- `storefront.session(await cookies())` becomes
+  `await storefront.serverStorefront()` in server code
+- SDK-provided `StorefrontSDKInitializer` is no longer the primary path
+- eager bootstrap moves to an explicit app-local client component that calls
+  `storefront.bootstrap()`
 
 ## Before / After
 
+### Package imports
+
+Before:
+
+```typescript
+import {
+  createStorefront,
+  type StorefrontRuntimeConfig,
+} from "@commercengine/storefront-sdk-nextjs";
+```
+
+After:
+
+```typescript
+import { Environment } from "@commercengine/storefront";
+import {
+  createNextjsStorefront,
+  type NextjsStorefrontConfig,
+} from "@commercengine/storefront/nextjs";
+```
+
+### App config
+
+Before:
+
+```typescript
+import {
+  createStorefront,
+  type StorefrontRuntimeConfig,
+} from "@commercengine/storefront-sdk-nextjs";
+
+const storefrontConfig: StorefrontRuntimeConfig = {
+  debug: true,
+  timeout: 15000,
+};
+
+export const storefront = createStorefront(storefrontConfig);
+```
+
+After:
+
+```typescript
+import { Environment } from "@commercengine/storefront";
+import {
+  createNextjsStorefront,
+  type NextjsStorefrontConfig,
+} from "@commercengine/storefront/nextjs";
+
+const storefrontConfig: NextjsStorefrontConfig = {
+  storeId: process.env.NEXT_PUBLIC_STORE_ID!,
+  apiKey: process.env.NEXT_PUBLIC_API_KEY!,
+  environment: Environment.Staging,
+  debug: true,
+  timeout: 15000,
+};
+
+export const storefront = createNextjsStorefront(storefrontConfig);
+```
+
 ### Public server reads
 
 Before:
 
 ```typescript
-const sdk = storefront({ isRootLayout: true });
+const sdk = storefront.public();
 const { data } = await sdk.catalog.listProducts();
 ```
 
 After:
 
 ```typescript
-const sdk = storefront.public();
+const sdk = storefront.publicStorefront();
 const { data } = await sdk.catalog.listProducts();
 ```
 
-### Server components, server actions, and route handlers
+### Client session usage
 
 Before:
 
 ```typescript
-const sdk = storefront(await cookies());
+const sdk = storefront.session();
 ```
 
 After:
 
 ```typescript
-const sdk = storefront.session(await cookies());
+const sdk = storefront.clientStorefront();
 ```
 
-### Client components
+### Server session usage
 
 Before:
 
 ```typescript
-const sdk = storefront();
+import { cookies } from "next/headers";
+
+const sdk = storefront.session(await cookies());
 ```
 
 After:
 
 ```typescript
-const sdk = storefront.session();
+const sdk = await storefront.serverStorefront();
 ```
 
-## New Mental Model
+## Bootstrap
 
-Use `storefront.public()` for:
+The new wrapper does not require an SDK-provided initializer component, but the
+recommended framework pattern is still to bootstrap eagerly in app code.
 
-- root layouts
-- static generation
-- ISR pages
-- public server-rendered catalog or helper reads
+Why this matters:
 
-Use `storefront.session()` / `storefront.session(await cookies())` for:
+- the browser can lazily bootstrap, but that is not the documented pattern
+- server actions and route handlers can also establish a session
+- but a cold Server Component request cannot be relied on to persist a newly
+  created anonymous session before later server reads depend on it
 
-- auth flows
-- cart reads and mutations
-- customer reads and mutations
-- order and payment flows
-- any request that should participate in anonymous or authenticated session
-  continuity
+Recommended bootstrap:
 
-## Root Layouts
+```tsx
+"use client";
 
-There is no special root-layout escape hatch anymore.
+import { useEffect } from "react";
+import { storefront } from "@/lib/storefront";
 
-Root layouts should:
+export function StorefrontBootstrap() {
+  useEffect(() => {
+    storefront.bootstrap().catch(console.error);
+  }, []);
 
-- use `storefront.public()` for public reads
-- mount `StorefrontSDKInitializer` to eagerly bootstrap the browser session
+  return null;
+}
+```
+
+Mount this once near the root of your app.
+
+## Mental Model
+
+Use:
+
+- `storefront.publicStorefront()` for build-safe public reads
+- `storefront.clientStorefront()` for browser session usage
+- `await storefront.serverStorefront()` for server components, route handlers,
+  and server actions
+- `storefront.bootstrap()` in a small app-local client component so session
+  continuity is established eagerly and explicitly
+
+The new wrapper still keeps the SDK core separate:
+
+- app/framework consumers use `@commercengine/storefront`
+- low-level advanced/custom users can still use `@commercengine/storefront-sdk`
+
+## Advanced Token Storage
+
+If you were manually wiring low-level server token storage before, prefer the
+high-level server accessor now:
+
+```typescript
+const sdk = await storefront.serverStorefront();
+```
 
-If a server component needs request-bound session continuity, move that call to a
-request-aware boundary and use `storefront.session(await cookies())`.
+If you still need low-level storage wiring, use `@commercengine/ssr-utils`
+directly rather than depending on this frozen package for new integrations.

package/README.md

@@ -1,5 +1,33 @@
 # CommerceEngine Next.js SDK
 
+> **Deprecated** — This package is superseded by
+> [`@commercengine/storefront/nextjs`](../storefront).
+>
+> This package is now on its **final legacy release line**. It is frozen for
+> migration only and will not receive new DX or framework work.
+>
+> Migrate to `@commercengine/storefront/nextjs`, which provides the actively
+> maintained Next.js API:
+>
+> - `storefront.publicStorefront()`
+> - `storefront.clientStorefront()`
+> - `await storefront.serverStorefront()`
+> - explicit app-local `storefront.bootstrap()` for eager session priming
+>
+> ```bash
+> pnpm add @commercengine/storefront
+> ```
+>
+> See the [`@commercengine/storefront` README](../storefront/README.md) and
+> [`MIGRATION.md`](./MIGRATION.md) for the direct migration path.
+
+---
+
+_The legacy documentation below is preserved only for teams that are still
+finishing migration from this frozen package._
+
+---
+
 Production-ready Next.js wrapper for the CommerceEngine Storefront SDK.
 
 Breaking changes from the previous wrapper API are documented in
@@ -12,8 +40,9 @@ explicit access patterns:
 - `storefront.session()` / `storefront.session(await cookies())` for live user
   session flows
 
-It builds on [`@commercengine/ssr-utils`](../ssr-utils) for cookie-backed server
-storage, but the primary DX is the Next.js-specific `createStorefront()` API.
+It builds on [`@commercengine/ssr-utils`](../ssr-utils) and its `createSSRFactory`
+for cookie-backed storage, singleton scoping, and bootstrap coordination. The
+primary DX is the Next.js-specific `createStorefront()` API.
 
 ## Installation
 
@@ -52,6 +81,11 @@ export const storefront = createStorefront(storefrontConfig);
 export type { StorefrontRuntimeConfig };
 ```
 
+`createStorefront()` stores the runtime config once for the app bundle and
+resets cached `public()` / client-side `session()` SDK instances when that
+config changes. In practice, define it once in `lib/storefront.ts` and reuse it
+everywhere.
+
 ### 3. Initialize once in the root layout
 
 ```typescript
@@ -271,9 +305,15 @@ type NextJSStorefront = {
     (): SessionStorefrontSDK;
     (cookieStore: NextCookieStore): SessionStorefrontSDK;
   };
+  bootstrap: () => Promise<void>;
 };
 ```
 
+`public()` returns the cached public SDK. `session()` returns the cached default
+client-side session SDK, while `session(await cookies())` creates the
+request-scoped server SDK for that request context. `bootstrap()` is a deduped
+client-side convenience for eagerly establishing an anonymous session.
+
 ### `StorefrontRuntimeConfig`
 
 Optional configuration object for `createStorefront()`:
@@ -360,6 +400,29 @@ storefront.session(await cookies());
 storefront.public();
 ```
 
+### Advanced server token storage
+
+For most apps, use `storefront.session(await cookies())` instead of manually
+creating server token storage.
+
+If you need the low-level path, `ServerTokenStorage` now expects a
+`CookieAdapter`, not the raw Next.js `cookies()` store:
+
+```typescript
+import {
+  ServerTokenStorage,
+  createCookieAdapter,
+} from "@commercengine/storefront-sdk-nextjs/server";
+import { cookies } from "next/headers";
+
+const tokenStorage = new ServerTokenStorage(
+  createCookieAdapter(await cookies())
+);
+```
+
+`bootstrapStorefrontSDK` is a client-side helper and should be imported from
+`@commercengine/storefront-sdk-nextjs/client`, not the `/server` entry.
+
 ### From direct core SDK usage
 
 ```typescript

package/dist/client.d.mts

@@ -1,7 +1,26 @@
-import { a as initializeStorefrontSDK, i as getSessionStorefrontSDK, l as ClientTokenStorage, n as StorefrontRuntimeConfig, r as getPublicStorefrontSDK, t as NextJSSDKConfig, u as NextJSTokenStorageOptions } from "./manager.mjs";
+import { a as getSessionStorefrontSDK, i as getPublicStorefrontSDK, n as StorefrontRuntimeConfig, o as initializeStorefrontSDK, r as bootstrapStorefrontSDK, t as NextJSSDKConfig } from "./manager.mjs";
 import { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, SessionStorefrontSDKOptions, StoreConfigClient, TokenStorage } from "@commercengine/storefront-sdk";
+import { ClientTokenStorage, SSRTokenStorageOptions as NextJSTokenStorageOptions } from "@commercengine/ssr-utils";
 
 //#region src/initializer.d.ts
+
+/**
+ * Client-side initialization component
+ * Use this in your root layout to initialize the SDK once
+ *
+ * Configuration is handled via environment variables:
+ * - NEXT_PUBLIC_STORE_ID
+ * - NEXT_PUBLIC_API_KEY
+ * - NEXT_PUBLIC_ENVIRONMENT (optional, defaults to staging)
+ *
+ * The core SDK middleware automatically handles everything:
+ * - Creates anonymous tokens automatically on first API request (if no tokens exist)
+ * - Token state assessment and cleanup on first request per page load
+ * - Expired token refresh with automatic anonymous fallback
+ * - Graceful handling of partial token states
+ *
+ * No manual token creation needed - just make API calls and everything works!
+ */
 interface StorefrontSDKInitializerProps {
   /**
    * Optional runtime configuration overrides for client-side API calls
@@ -13,4 +32,4 @@ declare function StorefrontSDKInitializer({
   runtimeConfig
 }?: StorefrontSDKInitializerProps): null;
 //#endregion
-export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, ClientTokenStorage, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, type NextJSSDKConfig, type NextJSTokenStorageOptions, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, type SessionStorefrontSDKOptions, StoreConfigClient, StorefrontSDKInitializer, type TokenStorage, getPublicStorefrontSDK, getSessionStorefrontSDK, initializeStorefrontSDK };
+export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, ClientTokenStorage, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, type NextJSSDKConfig, type NextJSTokenStorageOptions, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, type SessionStorefrontSDKOptions, StoreConfigClient, StorefrontSDKInitializer, type TokenStorage, bootstrapStorefrontSDK, getPublicStorefrontSDK, getSessionStorefrontSDK, initializeStorefrontSDK };

package/dist/client.mjs

@@ -1,41 +1,19 @@
 "use client";
 
-import { i as setGlobalStorefrontConfig, n as getSessionStorefrontSDK, o as ClientTokenStorage, r as initializeStorefrontSDK, t as getPublicStorefrontSDK } from "./manager.mjs";
+import { a as setGlobalStorefrontConfig, i as initializeStorefrontSDK, n as getPublicStorefrontSDK, r as getSessionStorefrontSDK, t as bootstrapStorefrontSDK } from "./manager.mjs";
 import { useEffect } from "react";
 import { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient } from "@commercengine/storefront-sdk";
+import { ClientTokenStorage } from "@commercengine/ssr-utils";
 
 //#region src/initializer.tsx
-/**
-* Client-side initialization component
-* Use this in your root layout to initialize the SDK once
-*
-* Configuration is handled via environment variables:
-* - NEXT_PUBLIC_STORE_ID
-* - NEXT_PUBLIC_API_KEY
-* - NEXT_PUBLIC_ENVIRONMENT (optional, defaults to staging)
-*
-* The core SDK middleware automatically handles everything:
-* - Creates anonymous tokens automatically on first API request (if no tokens exist)
-* - Token state assessment and cleanup on first request per page load
-* - Expired token refresh with automatic anonymous fallback
-* - Graceful handling of partial token states
-*
-* No manual token creation needed - just make API calls and everything works!
-*/
-/**
-* Bootstrap the client-side session if no access token exists yet.
-*/
-async function bootstrapSession() {
-	await getSessionStorefrontSDK().ensureAccessToken();
-}
 function StorefrontSDKInitializer({ runtimeConfig } = {}) {
 	useEffect(() => {
 		if (runtimeConfig) setGlobalStorefrontConfig(runtimeConfig);
 		else initializeStorefrontSDK();
-		bootstrapSession().catch(console.error);
+		bootstrapStorefrontSDK().catch(console.error);
 	}, [runtimeConfig]);
 	return null;
 }
 
 //#endregion
-export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, ClientTokenStorage, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient, StorefrontSDKInitializer, getPublicStorefrontSDK, getSessionStorefrontSDK, initializeStorefrontSDK };
+export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, ClientTokenStorage, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient, StorefrontSDKInitializer, bootstrapStorefrontSDK, getPublicStorefrontSDK, getSessionStorefrontSDK, initializeStorefrontSDK };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { n as StorefrontRuntimeConfig, o as NextCookieStore } from "./manager.mjs";
+import { n as StorefrontRuntimeConfig, s as NextCookieStore } from "./manager.mjs";
 import { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, PublicStorefrontSDK as PublicStorefrontSDK$1, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, SessionStorefrontSDK as SessionStorefrontSDK$1, StoreConfigClient } from "@commercengine/storefront-sdk";
 export * from "@commercengine/storefront-sdk";
 
@@ -11,6 +11,7 @@ export * from "@commercengine/storefront-sdk";
  * - `storefront.public()` for build/prerender-safe public reads
  * - `storefront.session()` in Client Components
  * - `storefront.session(cookies())` in server request contexts
+ * - `storefront.bootstrap()` in `StorefrontSDKInitializer` or custom client init
  */
 type NextJSStorefront = {
   public: () => PublicStorefrontSDK$1;
@@ -18,10 +19,15 @@ type NextJSStorefront = {
     (): SessionStorefrontSDK$1;
     (cookieStore: NextCookieStore): SessionStorefrontSDK$1;
   };
+  bootstrap: () => Promise<void>;
 };
 /**
  * Creates a configured storefront factory for Next.js.
  *
+ * The provided config is stored as the runtime default for this app instance.
+ * Updating that config resets the cached `public()` and client-side
+ * `session()` SDK singletons so future calls pick up the latest values.
+ *
  * Usage:
  * ```typescript
  * // lib/storefront.ts

package/dist/index.mjs

@@ -1,10 +1,14 @@
-import { i as setGlobalStorefrontConfig, n as getSessionStorefrontSDK, t as getPublicStorefrontSDK } from "./manager.mjs";
+import { a as setGlobalStorefrontConfig, n as getPublicStorefrontSDK, r as getSessionStorefrontSDK, t as bootstrapStorefrontSDK } from "./manager.mjs";
 import { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient } from "@commercengine/storefront-sdk";
 
 //#region src/storefront.ts
 /**
 * Creates a configured storefront factory for Next.js.
 *
+* The provided config is stored as the runtime default for this app instance.
+* Updating that config resets the cached `public()` and client-side
+* `session()` SDK singletons so future calls pick up the latest values.
+*
 * Usage:
 * ```typescript
 * // lib/storefront.ts
@@ -26,7 +30,8 @@ function createStorefront(config) {
 	}
 	return {
 		public: () => getPublicStorefrontSDK(),
-		session
+		session,
+		bootstrap: () => bootstrapStorefrontSDK()
 	};
 }
 

package/dist/manager.d.mts

@@ -1,49 +1,13 @@
-import { DebugLoggerFn, Environment, PublicStorefrontSDK, SessionStorefrontSDK, SessionStorefrontSDKOptions, SupportedDefaultHeaders, TokenStorage } from "@commercengine/storefront-sdk";
-import { SSRTokenStorageOptions, ServerTokenStorage } from "@commercengine/ssr-utils";
+import { DebugLoggerFn, Environment, PublicStorefrontSDK, SessionStorefrontSDK, SessionStorefrontSDKOptions, SupportedDefaultHeaders } from "@commercengine/storefront-sdk";
+import { SSRTokenStorageOptions, SSRTokenStorageOptions as NextJSTokenStorageOptions$1, ServerTokenStorage } from "@commercengine/ssr-utils";
 
-//#region src/client-storage.d.ts
+//#region src/server-storage.d.ts
 
 /**
- * Configuration options for NextJS token storage
- * Re-exported from ssr-utils for convenience
- */
-type NextJSTokenStorageOptions$1 = SSRTokenStorageOptions;
-/**
- * Client-side token storage that uses document.cookie
- *
- * This is Next.js specific because it needs to work with the same cookie
- * format as the server-side storage for seamless SSR/client hydration.
+ * Type for Next.js cookies (from next/headers).
  *
- * @example
- * ```typescript
- * import { ClientTokenStorage } from '@commercengine/storefront-sdk-nextjs/client';
- *
- * const storage = new ClientTokenStorage();
- * ```
- */
-declare class ClientTokenStorage implements TokenStorage {
-  private accessTokenKey;
-  private refreshTokenKey;
-  private options;
-  constructor(options?: NextJSTokenStorageOptions$1);
-  getAccessToken(): Promise<string | null>;
-  setAccessToken(token: string): Promise<void>;
-  getRefreshToken(): Promise<string | null>;
-  setRefreshToken(token: string): Promise<void>;
-  clearTokens(): Promise<void>;
-  private getCookie;
-  private setCookie;
-  private deleteCookie;
-}
-//#endregion
-//#region src/server-storage.d.ts
-/**
- * Configuration options for NextJS token storage
- * Re-exported from ssr-utils for convenience
- */
-type NextJSTokenStorageOptions = SSRTokenStorageOptions;
-/**
- * Type for Next.js cookies (from next/headers)
+ * This type remains local to the Next.js package so the `session(cookies())`
+ * overload stays framework-native.
  */
 type NextCookieStore = {
   get: (name: string) => {
@@ -52,22 +16,6 @@ type NextCookieStore = {
   set: (name: string, value: string, options?: Record<string, unknown>) => void;
   delete: (name: string) => void;
 };
-/**
- * Server-side token storage for Next.js using the cookies() API
- *
- * This wraps the ssr-utils ServerTokenStorage with a Next.js-specific adapter.
- *
- * @example
- * ```typescript
- * import { cookies } from 'next/headers';
- * import { ServerTokenStorage } from '@commercengine/storefront-sdk-nextjs/server';
- *
- * const storage = new ServerTokenStorage(cookies());
- * ```
- */
-declare class ServerTokenStorage$1 extends ServerTokenStorage {
-  constructor(cookieStore: NextCookieStore, options?: NextJSTokenStorageOptions);
-}
 //#endregion
 //#region src/manager.d.ts
 /**
@@ -77,8 +25,12 @@ interface NextJSSDKConfig extends Omit<SessionStorefrontSDKOptions, "tokenStorag
   /**
    * Token storage configuration options
    */
-  tokenStorageOptions?: NextJSTokenStorageOptions$1;
+  tokenStorageOptions?: NextJSTokenStorageOptions;
 }
+/**
+ * Token storage options re-exported from ssr-utils
+ */
+type NextJSTokenStorageOptions = SSRTokenStorageOptions;
 /**
  * Runtime configuration overrides that can be passed to `createStorefront()`
  * These override environment variables for that specific app instance.
@@ -105,7 +57,7 @@ interface StorefrontRuntimeConfig {
   /**
    * Token storage configuration
    */
-  tokenStorageOptions?: NextJSTokenStorageOptions$1;
+  tokenStorageOptions?: NextJSTokenStorageOptions;
 }
 /**
  * Get or create the public SDK singleton.
@@ -123,9 +75,15 @@ declare function getPublicStorefrontSDK(): PublicStorefrontSDK;
  */
 declare function getSessionStorefrontSDK(): SessionStorefrontSDK;
 declare function getSessionStorefrontSDK(cookieStore: NextCookieStore): SessionStorefrontSDK;
+/**
+ * Bootstrap the client-side session.
+ *
+ * Delegates to the SSR factory's deduped bootstrap. No-op on the server.
+ */
+declare function bootstrapStorefrontSDK(): Promise<void>;
 /**
  * Reset instantiated SDK singletons so they pick up current configuration.
  */
 declare function initializeStorefrontSDK(): void;
 //#endregion
-export { initializeStorefrontSDK as a, ServerTokenStorage$1 as c, getSessionStorefrontSDK as i, ClientTokenStorage as l, StorefrontRuntimeConfig as n, NextCookieStore as o, getPublicStorefrontSDK as r, NextJSTokenStorageOptions as s, NextJSSDKConfig as t, NextJSTokenStorageOptions$1 as u };
+export { getSessionStorefrontSDK as a, NextJSTokenStorageOptions$1 as c, getPublicStorefrontSDK as i, ServerTokenStorage as l, StorefrontRuntimeConfig as n, initializeStorefrontSDK as o, bootstrapStorefrontSDK as r, NextCookieStore as s, NextJSSDKConfig as t };

package/dist/manager.mjs

@@ -1,126 +1,17 @@
 import { cache } from "react";
 import { Environment, PublicStorefrontSDK, SessionStorefrontSDK } from "@commercengine/storefront-sdk";
-import { ServerTokenStorage } from "@commercengine/ssr-utils";
+import { createSSRFactory } from "@commercengine/ssr-utils";
 
-//#region src/client-storage.ts
-/**
-* Client-side token storage that uses document.cookie
-*
-* This is Next.js specific because it needs to work with the same cookie
-* format as the server-side storage for seamless SSR/client hydration.
-*
-* @example
-* ```typescript
-* import { ClientTokenStorage } from '@commercengine/storefront-sdk-nextjs/client';
-*
-* const storage = new ClientTokenStorage();
-* ```
-*/
-var ClientTokenStorage = class {
-	accessTokenKey;
-	refreshTokenKey;
-	options;
-	constructor(options = {}) {
-		const prefix = options.prefix || "ce_";
-		this.accessTokenKey = `${prefix}access_token`;
-		this.refreshTokenKey = `${prefix}refresh_token`;
-		const normalizedSameSite = options.sameSite ? {
-			strict: "Strict",
-			lax: "Lax",
-			none: "None"
-		}[options.sameSite] : "Lax";
-		this.options = {
-			maxAge: options.maxAge || 720 * 60 * 60,
-			path: options.path || "/",
-			domain: options.domain,
-			secure: options.secure ?? (typeof window !== "undefined" && window.location?.protocol === "https:"),
-			sameSite: normalizedSameSite
-		};
-	}
-	async getAccessToken() {
-		return this.getCookie(this.accessTokenKey);
-	}
-	async setAccessToken(token) {
-		this.setCookie(this.accessTokenKey, token);
-	}
-	async getRefreshToken() {
-		return this.getCookie(this.refreshTokenKey);
-	}
-	async setRefreshToken(token) {
-		this.setCookie(this.refreshTokenKey, token);
-	}
-	async clearTokens() {
-		this.deleteCookie(this.accessTokenKey);
-		this.deleteCookie(this.refreshTokenKey);
-	}
-	getCookie(name) {
-		if (typeof document === "undefined") return null;
-		const parts = `; ${document.cookie}`.split(`; ${name}=`);
-		if (parts.length === 2) {
-			const cookieValue = parts.pop()?.split(";").shift();
-			return cookieValue ? decodeURIComponent(cookieValue) : null;
-		}
-		return null;
-	}
-	setCookie(name, value) {
-		if (typeof document === "undefined") return;
-		let cookieString = `${name}=${encodeURIComponent(value)}`;
-		if (this.options.maxAge) cookieString += `; Max-Age=${this.options.maxAge}`;
-		if (this.options.path) cookieString += `; Path=${this.options.path}`;
-		if (this.options.domain) cookieString += `; Domain=${this.options.domain}`;
-		if (this.options.secure) cookieString += `; Secure`;
-		if (this.options.sameSite) cookieString += `; SameSite=${this.options.sameSite}`;
-		document.cookie = cookieString;
-	}
-	deleteCookie(name) {
-		if (typeof document === "undefined") return;
-		let cookieString = `${name}=; Max-Age=0`;
-		if (this.options.path) cookieString += `; Path=${this.options.path}`;
-		if (this.options.domain) cookieString += `; Domain=${this.options.domain}`;
-		document.cookie = cookieString;
-	}
-};
-
-//#endregion
-//#region src/server-storage.ts
-/**
-* Server-side token storage for Next.js using the cookies() API
-*
-* This wraps the ssr-utils ServerTokenStorage with a Next.js-specific adapter.
-*
-* @example
-* ```typescript
-* import { cookies } from 'next/headers';
-* import { ServerTokenStorage } from '@commercengine/storefront-sdk-nextjs/server';
-*
-* const storage = new ServerTokenStorage(cookies());
-* ```
-*/
-var ServerTokenStorage$1 = class extends ServerTokenStorage {
-	constructor(cookieStore, options = {}) {
-		super({
-			get: (name) => cookieStore.get(name)?.value ?? null,
-			set: (name, value, opts) => cookieStore.set(name, value, opts),
-			delete: (name) => cookieStore.delete(name)
-		}, options);
-	}
-};
-
-//#endregion
 //#region src/manager.ts
 /**
-* Global runtime configuration storage
+* Global runtime configuration storage.
 * This gets bundled into both client and server bundles.
 */
 let globalStorefrontConfig = null;
 /**
-* Client-side session SDK singleton (only lives in browser)
-*/
-let clientSessionSDK = null;
-/**
-* Public SDK singleton shared by non-session reads
+* Cached SSR factory — invalidated when global config changes.
 */
-let publicSDK = null;
+let ssrFactory = null;
 /**
 * Get configuration from environment variables merged with global config.
 * Precedence order: environment variables < global config
@@ -187,23 +78,45 @@ function buildPublicSDKConfig(config) {
 	if (config.defaultHeaders) publicConfig.defaultHeaders = config.defaultHeaders;
 	return publicConfig;
 }
-function createClientSessionSDK(config) {
-	return new SessionStorefrontSDK({
-		...config,
-		tokenStorage: new ClientTokenStorage(config.tokenStorageOptions)
-	});
-}
-function createServerSessionSDK(cookieStore, config) {
-	return new SessionStorefrontSDK({
-		...config,
-		tokenStorage: new ServerTokenStorage$1(cookieStore, config.tokenStorageOptions)
-	});
+/**
+* Get or create the SSR factory.
+*
+* The factory is lazily created on first access and invalidated when
+* global config changes via {@link setGlobalStorefrontConfig} or
+* {@link initializeStorefrontSDK}.
+*/
+function getFactory() {
+	if (!ssrFactory) {
+		const config = getConfig();
+		ssrFactory = createSSRFactory({
+			createPublicSDK: () => new PublicStorefrontSDK(buildPublicSDKConfig(config)),
+			createClientSessionSDK: (tokenStorage) => new SessionStorefrontSDK({
+				...config,
+				tokenStorage
+			}),
+			createServerSessionSDK: (_cookieStore, tokenStorage) => new SessionStorefrontSDK({
+				...config,
+				tokenStorage
+			}),
+			createServerCookieAdapter: (cookieStore) => ({
+				get: (name) => cookieStore.get(name)?.value ?? null,
+				set: (name, value, opts) => cookieStore.set(name, value, opts),
+				delete: (name) => cookieStore.delete(name)
+			}),
+			bootstrapSession: (sdk) => sdk.ensureAccessToken().then(() => {}),
+			tokenStorageOptions: config.tokenStorageOptions
+		});
+	}
+	return ssrFactory;
 }
 /**
-* Request-scoped server session SDK factory using React cache
+* Request-scoped server session SDK using React cache for dedup.
+*
+* React `cache()` deduplicates calls with the same `cookieStore` reference
+* within a single server request, avoiding redundant SDK instantiation.
 */
 const getServerSessionSDKCached = cache((cookieStore) => {
-	return createServerSessionSDK(cookieStore, getConfig());
+	return getFactory().session(cookieStore);
 });
 /**
 * Get or create the public SDK singleton.
@@ -212,48 +125,40 @@ const getServerSessionSDKCached = cache((cookieStore) => {
 * participate in session bootstrap, refresh, or storage writes.
 */
 function getPublicStorefrontSDK() {
-	const config = getConfig();
-	if (!publicSDK) publicSDK = new PublicStorefrontSDK(buildPublicSDKConfig(config));
-	return publicSDK;
+	return getFactory().public();
 }
 function getSessionStorefrontSDK(cookieStore) {
 	if (typeof window !== "undefined") {
 		if (cookieStore) console.warn("Cookie store passed in client environment - this will be ignored");
-		const config = getConfig();
-		if (!clientSessionSDK) clientSessionSDK = createClientSessionSDK(config);
-		return clientSessionSDK;
+		return getFactory().session();
 	}
 	if (cookieStore) return getServerSessionSDKCached(cookieStore);
-	throw new Error([
-		"🚨 Server session access requires cookies!",
-		"",
-		"You're calling the session SDK on the server without cookies.",
-		"",
-		"✅ Correct usage for user/session-aware requests:",
-		"  import { cookies } from 'next/headers'",
-		"  const sdk = storefront.session(cookies())",
-		"",
-		"✅ Correct usage for build/prerender-safe public reads:",
-		"  const sdk = storefront.public()",
-		"",
-		"This keeps public rendering separate from real user session continuity."
-	].join("\n"));
+	return getFactory().session();
+}
+/**
+* Bootstrap the client-side session.
+*
+* Delegates to the SSR factory's deduped bootstrap. No-op on the server.
+*/
+function bootstrapStorefrontSDK() {
+	return getFactory().bootstrap();
 }
 /**
 * Set global storefront configuration that applies to all SDK instances.
+*
+* Resetting the cached factory here keeps `createStorefront(config)`
+* deterministic even though runtime config is stored globally for the bundle.
 */
 function setGlobalStorefrontConfig(config) {
 	globalStorefrontConfig = config;
-	clientSessionSDK = null;
-	publicSDK = null;
+	ssrFactory = null;
 }
 /**
 * Reset instantiated SDK singletons so they pick up current configuration.
 */
 function initializeStorefrontSDK() {
-	clientSessionSDK = null;
-	publicSDK = null;
+	ssrFactory = null;
 }
 
 //#endregion
-export { ServerTokenStorage$1 as a, setGlobalStorefrontConfig as i, getSessionStorefrontSDK as n, ClientTokenStorage as o, initializeStorefrontSDK as r, getPublicStorefrontSDK as t };
+export { setGlobalStorefrontConfig as a, initializeStorefrontSDK as i, getPublicStorefrontSDK as n, getSessionStorefrontSDK as r, bootstrapStorefrontSDK as t };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { a as initializeStorefrontSDK, c as ServerTokenStorage, i as getSessionStorefrontSDK, r as getPublicStorefrontSDK, s as NextJSTokenStorageOptions, t as NextJSSDKConfig } from "./manager.mjs";
+import { a as getSessionStorefrontSDK, c as NextJSTokenStorageOptions, i as getPublicStorefrontSDK, l as ServerTokenStorage, o as initializeStorefrontSDK, t as NextJSSDKConfig } from "./manager.mjs";
 import { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient } from "@commercengine/storefront-sdk";
 export * from "@commercengine/storefront-sdk";
 export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, type NextJSSDKConfig, type NextJSTokenStorageOptions, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, ServerTokenStorage, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient, getPublicStorefrontSDK, getSessionStorefrontSDK, initializeStorefrontSDK };

package/dist/server.mjs

@@ -1,5 +1,6 @@
-import { a as ServerTokenStorage, n as getSessionStorefrontSDK, r as initializeStorefrontSDK, t as getPublicStorefrontSDK } from "./manager.mjs";
+import { i as initializeStorefrontSDK, n as getPublicStorefrontSDK, r as getSessionStorefrontSDK } from "./manager.mjs";
 import { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, PaymentsClient, PublicCatalogClient, PublicHelpersClient, PublicStoreConfigClient, PublicStorefrontAPIClient, PublicStorefrontSDK, ResponseUtils, SessionStorefrontAPIClient, SessionStorefrontSDK, StoreConfigClient } from "@commercengine/storefront-sdk";
+import { ServerTokenStorage } from "@commercengine/ssr-utils";
 
 export * from "@commercengine/storefront-sdk"
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commercengine/storefront-sdk-nextjs",
-  "version": "0.3.0",
-  "description": "Next.js wrapper for the Commerce Engine Storefront SDK",
+  "version": "0.4.0",
+  "description": "Legacy frozen Next.js wrapper for the Commerce Engine Storefront SDK",
   "type": "module",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -34,7 +34,9 @@
     "api",
     "sdk",
     "nextjs",
-    "react"
+    "react",
+    "legacy",
+    "deprecated"
   ],
   "author": "Commerce Engine",
   "license": "All rights reserved",
@@ -44,8 +46,8 @@
     "react-dom": ">=19.0.0"
   },
   "dependencies": {
-    "@commercengine/storefront-sdk": "0.14.0",
-    "@commercengine/ssr-utils": "0.2.0"
+    "@commercengine/storefront-sdk": "0.14.2",
+    "@commercengine/ssr-utils": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",