npm - @commercengine/storefront-sdk-nextjs - Versions diffs - 0.1.0-alpha.1 → 1.0.0-alpha.3 - Mend

@commercengine/storefront-sdk-nextjs 0.1.0-alpha.1 → 1.0.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.md +333 -440
package/dist/client.cjs +68 -93
package/dist/client.d.cts +40 -57
package/dist/client.d.ts +40 -57
package/dist/client.js +68 -88
package/dist/index.cjs +142 -92
package/dist/index.d.cts +29 -94
package/dist/index.d.ts +29 -94
package/dist/index.js +142 -82
package/dist/server-ByBPoXJG.d.cts +182 -0
package/dist/server-ByBPoXJG.d.ts +182 -0
package/dist/server-CwxgXezP.d.cts +115 -0
package/dist/server-CwxgXezP.d.ts +115 -0
package/dist/server.cjs +57 -88
package/dist/server.d.cts +1 -2
package/dist/server.d.ts +1 -2
package/dist/server.js +57 -84
package/dist/storefront.cjs +93 -21
package/dist/storefront.d.cts +2 -40
package/dist/storefront.d.ts +2 -40
package/dist/storefront.js +93 -21
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,14 +1,15 @@
 # CommerceEngine Next.js SDK
-**Production-ready Next.js wrapper** for the CommerceEngine Storefront SDK. Handles the complexities of Next.js runtime environments, automatic token management, and cookie-based authentication across all contexts.
+**Production-ready Next.js wrapper** for the CommerceEngine Storefront SDK. Provides the perfect developer experience with automatic context detection, universal API, and zero configuration complexity.
-**✨ What makes this special:**
-- **🎯 Universal API** - Single `storefront()` function works everywhere
+**✨ Perfect DX Pattern:**
+- **🎯 One Config File** - Single `lib/storefront.ts` using `createStorefront()`
+- **🌍 Universal API** - Same `storefront()` import works everywhere
 - **🔥 Automatic Tokens** - Creates and manages tokens automatically
-- **🧠 Smart Environment Detection** - Detects Server vs Client contexts
+- **🧠 Smart Context Detection** - Detects Server vs Client vs Build contexts
 - **🍪 Cookie-based State** - Shared authentication via Next.js cookies
 - **⚡ Request Isolation** - Proper per-request SDK instances on server
-- **🛠 Zero Configuration** - Works with environment variables out of the box
+- **🛠 Zero Complexity** - Environment variables + one lib file = done
 ## Installation
@@ -20,35 +21,82 @@ pnpm add @commercengine/storefront-sdk-nextjs
 ## Quick Start
-### 1. Environment Variables
+### 1. Environment Variables (Required)
 Add your store configuration to `.env.local`:
 ```bash
 NEXT_PUBLIC_STORE_ID=your-store-id
-NEXT_PUBLIC_ENVIRONMENT=staging  # or "production"
 NEXT_PUBLIC_API_KEY=your-api-key
+# Environment (defaults to "staging")
+NEXT_PUBLIC_ENVIRONMENT=staging  # or "production"
+```
+### 2. Create Your Storefront Configuration
+Create `lib/storefront.ts` in your project:
+```typescript
+// lib/storefront.ts
+import {
+  createStorefront,
+  type StorefrontRuntimeConfig,
+} from "@commercengine/storefront-sdk-nextjs";
+// Optional advanced configuration (everything not in environment variables)
+const storefrontConfig: StorefrontRuntimeConfig = {
+  debug: true,
+  timeout: 15000,
+  logger: (msg: string, ...args: any[]) =>
+    console.log("[STOREFRONT]", msg, ...args),
+  onTokensUpdated: (access: string, refresh: string) => {
+    console.log("🔥 TOKENS UPDATED:", {
+      access: access.slice(0, 20) + "...",
+      refresh: refresh.slice(0, 20) + "...",
+    });
+  },
+  onTokensCleared: () => {
+    console.log("🔄 TOKENS CLEARED");
+  },
+};
+// Create the configured storefront function (storefrontConfig is OPTIONAL)
+export const storefront = createStorefront(storefrontConfig);
+// Re-export types for convenience
+export type { StorefrontRuntimeConfig };
+```
+**All Core SDK Types Available:**
+The Next.js SDK re-exports all types from the core SDK, so you can import them directly:
+```typescript
+// Import any core SDK types you need
+import type {
+  UserInfo,
+  SupportedDefaultHeaders,
+  StorefrontSDKOptions,
+  components,
+  operations
+} from "@commercengine/storefront-sdk-nextjs";
+// Use imported types
+const headers: SupportedDefaultHeaders = {
+  customer_group_id: "01ABC123..."
+};
 ```
-### 2. Initialize in Root Layout
+### 3. Initialize in Root Layout
 ```typescript
 // app/layout.tsx
-import { Environment, StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
-        <StorefrontSDKInitializer
-          config={{
-            storeId: process.env.NEXT_PUBLIC_STORE_ID || "",
-            environment: process.env.NEXT_PUBLIC_ENVIRONMENT === "production"
-              ? Environment.Production
-              : Environment.Staging,
-            apiKey: process.env.NEXT_PUBLIC_API_KEY,
-          }}
-        />
+        <StorefrontSDKInitializer />
         {children}
       </body>
     </html>
@@ -56,57 +104,39 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
-### 3. Use Anywhere with the Universal API
+### 4. Use Anywhere with Universal Import
 ```typescript
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
-import { cookies } from "next/headers";
+// Import your configured storefront everywhere
+import { storefront } from "@/lib/storefront";
+import { cookies } from "next/headers"; // Only for server contexts
-// Client Component - No cookies needed
+// ✅ Client Component - No cookies needed
 const products = await storefront().catalog.listProducts();
-// Server Component, Server Action, or API Route
+// ✅ Server Component, Server Action, or API Route - MUST pass cookies
 const products = await storefront(cookies()).catalog.listProducts();
-```
-## Usage in Different Next.js Contexts
-### Server Components
-Server Components run on the server and can **read** cookies but cannot **write** them. Each request gets its own SDK instance with independent token management.
+// ✅ Root Layout - Special exception with explicit flag
+const products = await storefront({ isRootLayout: true }).catalog.listProducts();
-```typescript
-// app/products/page.tsx
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
-import { cookies } from "next/headers";
-export default async function ProductsPage() {
-  const sdk = storefront(cookies());
-  // This will generate a new anonymous token for this request
-  // Note: Token cannot be persisted (cookies are read-only in Server Components)
-  const { data: products } = await sdk.catalog.listProducts();
-  return (
-    <div>
-      {products?.products.map(product => (
-        <div key={product.id}>{product.name}</div>
-      ))}
-    </div>
-  );
-}
+// ✅ SSG/ISR (build contexts) - Automatic fallback to memory storage
+// (NEXT_BUILD_CACHE_TOKENS=true enables this)
+const products = await storefront().catalog.listProducts();
 ```
+## Usage in Different Next.js Contexts
 ### Client Components
-Client Components run in the browser and can both read and write cookies, enabling persistent authentication.
+Client Components run in the browser and can persist tokens via cookies:
 ```typescript
 // components/ProductList.tsx
 "use client";
 import { useState, useEffect } from "react";
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { storefront } from "@/lib/storefront";
 export default function ProductList() {
   const [products, setProducts] = useState([]);
@@ -115,7 +145,7 @@ export default function ProductList() {
     async function loadProducts() {
       const sdk = storefront(); // No cookies() needed on client-side
-      // This will create and persist tokens via cookies
+      // Tokens are automatically managed by StorefrontSDKInitializer
       const { data } = await sdk.catalog.listProducts();
       if (data) setProducts(data.products);
     }
@@ -133,51 +163,62 @@ export default function ProductList() {
 }
 ```
+### Server Components
+Server Components run on the server and can read cookies:
+```typescript
+// app/products/page.tsx
+import { storefront } from "@/lib/storefront";
+import { cookies } from "next/headers";
+export default async function ProductsPage() {
+  const sdk = storefront(cookies());
+  const { data: products } = await sdk.catalog.listProducts();
+  return (
+    <div>
+      {products?.products.map(product => (
+        <div key={product.id}>{product.name}</div>
+      ))}
+    </div>
+  );
+}
+```
 ### Server Actions
-Server Actions run on the server and can both read and write cookies, making them perfect for authentication flows.
+Server Actions can both read and write cookies, perfect for authentication:
 ```typescript
 // app/actions.ts
 "use server";
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { storefront } from "@/lib/storefront";
 import { cookies } from "next/headers";
 export async function loginWithEmail(email: string, password: string) {
   const sdk = storefront(cookies());
-  // This will create and persist tokens via cookies
   const { data, error } = await sdk.auth.loginWithPassword({ email, password });
   if (data) {
-    // Tokens are automatically saved to cookies by the SDK
+    // Tokens are automatically saved to cookies
     return { success: true, user: data.user };
   }
   return { success: false, error: error?.message };
 }
-export async function addToCart(productId: string, quantity: number) {
-  const sdk = storefront(cookies());
-  // Uses existing authentication from cookies
-  const { data } = await sdk.cart.addItem({
-    product_id: productId,
-    quantity
-  });
-  return data;
-}
 ```
 ### API Routes
-API Routes work identically to Server Actions - they can read and write cookies.
+API Routes work identically to Server Actions:
 ```typescript
 // app/api/products/route.ts
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { storefront } from "@/lib/storefront";
 import { cookies } from "next/headers";
 import { NextResponse } from "next/server";
@@ -198,167 +239,41 @@ export async function GET() {
     );
   }
 }
-## Authentication Patterns
-### Anonymous Users
-The SDK automatically creates anonymous tokens when needed:
-```typescript
-// This works in any context - creates anonymous token automatically
-const { data: products } = await storefront(cookies()).catalog.listProducts();
 ```
-### Email/Password Login
+### Root Layout (Special Case)
-```typescript
-// Server Action
-"use server";
-export async function loginUser(email: string, password: string) {
-  const sdk = storefront(cookies());
-  const { data, error } = await sdk.auth.loginWithPassword({ email, password });
-  if (data) {
-    // Tokens automatically saved to cookies
-    redirect('/dashboard');
-  }
-  return { error: error?.message };
-}
-```
-### Phone/OTP Login
+Root Layout requires explicit flag since it's outside request context. Passing this flag will instruct the SDK to fallback to MemoryStore when rendering the root layout as the root layout runs on both server and client before cookie context is available.
 ```typescript
-// Server Action - Step 1: Send OTP
-export async function sendOTP(phone: string, country_code: string) {
-  const sdk = storefront(cookies());
-  return await sdk.auth.loginWithPhone({
-    phone,
-    country_code,
-    register_if_not_exists: true
-  });
-}
-// Server Action - Step 2: Verify OTP
-export async function verifyOTP(otp: string, otp_token: string, otp_action: string) {
-  const sdk = storefront(cookies());
-  const { data, error } = await sdk.auth.verifyOtp({
-    otp,
-    otp_token,
-    otp_action
-  });
-  if (data) {
-    // Tokens automatically saved to cookies
-    return { success: true, user: data.user };
-  }
-  return { success: false, error: error?.message };
-}
-```
-## Token Management & Cookie Behavior
-### How It Works
-1. **Server Components**: Generate tokens but can't persist them (read-only cookies)
-2. **Client Components**: Generate and persist tokens via `document.cookie`
-3. **Server Actions/API Routes**: Generate and persist tokens via Next.js `cookies()`
-4. **Shared State**: All contexts read from the same cookie storage
-### Cookie Configuration
-The SDK uses secure cookies with sensible defaults:
-```typescript
-// Advanced cookie configuration (optional)
-<StorefrontSDKInitializer
-  config={{
-    storeId: "your-store-id",
-    apiKey: "your-api-key",
-    tokenStorageOptions: {
-      prefix: "ce_",               // Cookie name prefix
-      maxAge: 30 * 24 * 60 * 60,   // 30 days
-      path: "/",
-      secure: true,                // HTTPS only (auto-detected)
-      sameSite: "Lax",
-    }
-  }}
-/>
-```
-## API Reference
-### `storefront()`
-**Universal function** that works in all Next.js contexts:
-```typescript
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
-import { cookies } from "next/headers";
-// ✅ Client-side (browser)
-const sdk = storefront();
-// ✅ Server-side (requires cookies for token persistence)
-const sdk = storefront(cookies());
-// ❌ Server-side without cookies (helpful error message)
-const sdk = storefront(); // Throws clear error with instructions
-```
-### `StorefrontSDKInitializer`
-**Client-side initializer** component (must be imported from `/client`):
-```typescript
-import { Environment, StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
-<StorefrontSDKInitializer
-  config={{
-    storeId: "your-store-id",
-    environment: Environment.Production, // or Environment.Staging
-    apiKey: "your-api-key",
-    // Optional: Advanced configuration
-    tokenStorageOptions: {
-      prefix: "ce_",               // Cookie prefix (default)
-      maxAge: 30 * 24 * 60 * 60,   // 30 days
-      secure: true,                // Auto-detected from environment
-      sameSite: "Lax",
-    },
-  }}
-/>
-```
-## Error Handling
-All SDK methods return a consistent error structure:
+// app/layout.tsx
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+import { storefront } from "@/lib/storefront";
-```typescript
-const { data, error, response } = await storefront(cookies()).catalog.listProducts();
+// Root Layout requires explicit flag - no request context available
+const sdk = storefront({ isRootLayout: true });
+const { data: storeConfig } = await sdk.store.getStoreConfig();
-if (error) {
-  console.error("API Error:", error.message, error.code);
-  console.log("Status:", response.status);
-} else {
-  console.log("Products:", data.products);
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <StorefrontSDKInitializer />
+        <h1>Welcome to {storeConfig?.store_config?.brand.name}</h1>
+        {children}
+      </body>
+    </html>
+  );
 }
 ```
 ## Static Site Generation (SSG) & Build-Time Optimization
-The SDK provides powerful build-time optimizations for SSG/ISR that dramatically reduce API calls during the build process through intelligent token caching.
+The SDK provides powerful build-time optimizations through intelligent token caching.
-### Automatic Build-Time Token Caching
+### Configure Next.js for Build-Time Optimization
-Enable automatic token caching during production builds:
+Create or update your `next.config.ts` (or `next.config.js`) to enable automatic token caching during builds:
 ```typescript
 // next.config.ts
@@ -370,9 +285,14 @@ const nextConfig = (phase: string): NextConfig => {
   return {
     env: {
-      // Enable build-time token caching during production builds
+      // Enable build-time token caching during production builds and when explicitly set
       NEXT_BUILD_CACHE_TOKENS: process.env.NEXT_BUILD_CACHE_TOKENS ?? (isBuild ? 'true' : 'false'),
+      // Critical: tells SDK to use MemoryStore during SSG/Build/ISR to avoid cookie context failures
+      NEXT_IS_BUILD: isBuild ? 'true' : 'false',
     },
+    // Ensure static generation is enabled
+    output: undefined, // Let Next.js decide based on usage
   };
 };
@@ -381,11 +301,9 @@ export default nextConfig;
 ### SSG with generateStaticParams
-Create static product pages during build:
 ```typescript
 // app/products/[slug]/page.tsx
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { storefront } from "@/lib/storefront";
 import { notFound } from "next/navigation";
 interface ProductPageProps {
@@ -396,7 +314,6 @@ export default async function ProductPage({ params }: ProductPageProps) {
   const { slug } = await params;
   const sdk = storefront(); // No cookies() - uses build-time storage
-  // Get product detail by slug or ID
   const { data, error } = await sdk.catalog.getProductDetail({
     product_id_or_slug: slug
   });
@@ -405,28 +322,24 @@ export default async function ProductPage({ params }: ProductPageProps) {
     notFound();
   }
-  const { product } = data;
   return (
     <div>
-      <h1>{product.name}</h1>
-      <p>SKU: {product.sku}</p>
-      <p>Type: {product.product_type}</p>
-      <p>Description: {product.short_description}</p>
+      <h1>{data.product.name}</h1>
+      <p>SKU: {data.product.sku}</p>
+      <p>Description: {data.product.short_description}</p>
     </div>
   );
 }
 // Generate static params from real API data
 export async function generateStaticParams() {
-  const sdk = storefront(); // No cookies() - uses build-time storage
+  const sdk = storefront(); // Token will be cached and reused
   const { data: productsData, error } = await sdk.catalog.listProducts({
-    limit: 100 // Generate pages for first 100 products
+    limit: 100
   });
   if (error || !productsData) {
-    console.error("Error fetching products for static generation:", error);
     return [];
   }
@@ -436,181 +349,243 @@ export async function generateStaticParams() {
 }
 ```
-### SSG Test Page Example
+### Build Performance Benefits
+With token caching enabled:
+- ✅ Token created once and reused across all pages
+- ✅ 100 pages = ~1 anonymous token API call total
+- ✅ Faster builds, dramatically lower API usage
+## Authentication Patterns
+> **⚠️ Important:** Any authentication endpoint that returns tokens (like `loginWithPassword`, `verifyOtp`, `register`, etc.) **must** be called in contexts where cookies can be set and managed:
+> - ✅ **Server Actions** (recommended for authentication flows)
+> - ✅ **API Routes** (`/api` directory)
+> - ✅ **Client Components** (browser environment)
+> - ❌ **Server Components** (cannot set cookies, tokens won't persist)
+>
+> This ensures the SDK can automatically handle token storage and user session continuity.
-Create a page that makes multiple API calls during build to test token reuse:
+### Anonymous Users
+The SDK automatically creates anonymous tokens via the `StorefrontSDKInitializer` component imported in your root layout. If this component is not imported (not recommended), a new token will be minted for each request as a fallback. **It is highly recommended** to use the `StorefrontSDKInitializer` and ensure all token-returning endpoints are called from request contexts that can set cookies. [Authentication Patterns](#authentication-patterns).
 ```typescript
-// app/ssg-test/page.tsx
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
+// This works everywhere - creates anonymous token automatically
+const { data: products } = await storefront(cookies()).catalog.listProducts();
+```
-export default async function SSGTestPage() {
-  const sdk = storefront(); // No cookies() - uses build-time storage
+### Email/Password Login
+```typescript
+// Server Action (✅ Recommended - can set cookies for token persistence)
+"use server";
+export async function loginUser(email: string, password: string) {
+  const sdk = storefront(cookies());
+  const { data, error } = await sdk.auth.loginWithPassword({ email, password });
+  if (data) {
+    // Tokens automatically saved to cookies
+    redirect('/dashboard');
+  }
-  // Make multiple API calls - token will be created once and reused
-  const { data: products, error: productsError } = await sdk.catalog.listProducts({
-    limit: 10
+  return { error: error?.message };
+}
+```
+### Phone/OTP Login
+```typescript
+// Server Action - Step 1: Send OTP (✅ Recommended context)
+export async function sendOTP(phone: string, country_code: string) {
+  const sdk = storefront(await cookies());
+  return await sdk.auth.loginWithPhone({
+    phone,
+    country_code,
+    register_if_not_exists: true
   });
+}
+// Server Action - Step 2: Verify OTP (✅ Recommended - can set cookies for token persistence)
+export async function verifyOTP(otp: string, otp_token: string, otp_action: string) {
+  const sdk = storefront(await cookies());
-  const { data: categories, error: categoriesError } = await sdk.catalog.listCategories({
-    nested_level: 1
+  const { data, error } = await sdk.auth.verifyOtp({
+    otp,
+    otp_token,
+    otp_action
   });
-  const { data: anonymousToken, error: tokenError } = await sdk.auth.getAnonymousToken();
+  if (data) {
+    // Tokens automatically saved to cookies
+    return { success: true, user: data.user };
+  }
-  const buildTime = new Date().toISOString();
+  return { success: false, error: error?.message };
+}
+```
+## API Reference
+### `createStorefront(config?)`
+Creates a configured storefront function that works universally across all Next.js contexts.
+```typescript
+import { createStorefront } from "@commercengine/storefront-sdk-nextjs";
+export const storefront = createStorefront({
+  debug: true,
+  logger: (msg, ...args) => console.log('[DEBUG]', msg, ...args)
+});
+```
+**Parameters:**
+- `config` (optional): `StorefrontRuntimeConfig` - Advanced configuration options
+**Returns:**
+- Universal `storefront()` function that works in all Next.js contexts
+### `StorefrontRuntimeConfig`
+Optional configuration object for `createStorefront()`:
+```typescript
+interface StorefrontRuntimeConfig {
+  // Override environment variables
+  storeId?: string;
+  apiKey?: string;
+  environment?: Environment;
+  baseUrl?: string;
+  timeout?: number;
+  debug?: boolean;
-  return (
-    <div>
-      <h1>SSG Test Page</h1>
-      <p><strong>Built at:</strong> {buildTime}</p>
-      <div>
-        <h2>Build-time API Results:</h2>
-        <div>
-          <h3>Products Call:</h3>
-          {productsError ? (
-            <p style={{ color: 'red' }}>Error: {productsError.message}</p>
-          ) : (
-            <p>✅ Success: Found {products?.products?.length || 0} products</p>
-          )}
-        </div>
-        <div>
-          <h3>Categories Call:</h3>
-          {categoriesError ? (
-            <p style={{ color: 'red' }}>Error: {categoriesError.message}</p>
-          ) : (
-            <p>✅ Success: Found {categories?.categories?.length || 0} categories</p>
-          )}
-        </div>
-        <div>
-          <h3>Anonymous Token Call:</h3>
-          {tokenError ? (
-            <p style={{ color: 'red' }}>Error: {tokenError.message}</p>
-          ) : (
-            <p>✅ Success: User ID {anonymousToken?.user?.id}</p>
-          )}
-        </div>
-      </div>
-    </div>
-  );
+  // Advanced options (not available via environment variables)
+  accessToken?: string;
+  refreshToken?: string;
+  defaultHeaders?: SupportedDefaultHeaders;
+  logger?: (message: string, ...args: any[]) => void;
+  onTokensUpdated?: (accessToken: string, refreshToken: string) => void;
+  onTokensCleared?: () => void;
+  tokenStorageOptions?: NextJSTokenStorageOptions;
 }
 ```
-### Build Performance Benefits
+### Universal `storefront()` Function
-With token caching enabled, you'll see dramatic performance improvements:
+The function returned by `createStorefront()` works in all contexts with strict enforcement:
-**Without Caching:**
-- 🔴 Each page creates its own token
-- 🔴 100 pages = 100+ anonymous token API calls
-- 🔴 Slower builds, higher API usage
+```typescript
+// Client-side (browser)
+const sdk = storefront();
-**With Caching:**
-- ✅ Token created once and reused across all pages
-- ✅ 100 pages = ~3 anonymous token API calls total
-- ✅ Faster builds, dramatically lower API usage
+// Server-side (requires cookies for user continuity)
+const sdk = storefront(cookies());
+// Root Layout (special exception with explicit flag)
+const sdk = storefront({ isRootLayout: true });
-### Build Logs to Monitor
+// Server-side without cookies - throws helpful error to protect user sessions
+const sdk = storefront(); // ❌ Throws error in server contexts
+```
-When build caching is working, you'll see these logs:
+### Function Signatures
+```typescript
+function storefront(): StorefrontSDK;
+function storefront(cookieStore: NextCookieStore): StorefrontSDK;
+function storefront(options: { isRootLayout: true }): StorefrontSDK;
+function storefront(cookieStore: NextCookieStore, options: { isRootLayout?: boolean }): StorefrontSDK;
 ```
-🚀 [BuildCache] Using BuildCachingMemoryTokenStorage with key: store:staging
-🟡 [BuildCache] No cached token found for key: store:staging
-🟠 [BuildCache] Caching new access token for key: store:staging
-🔵 [BuildCache] Using instance token for key: store:staging
-🟢 [BuildCache] Using cached token for key: store:staging
+### `StorefrontSDKInitializer`
+Client-side initializer component (must be imported from `/client`):
+```typescript
+import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
+<StorefrontSDKInitializer />
 ```
-**Key Indicators:**
-- ✅ Only 1-3 "Automatically created anonymous session" messages
-- ✅ Many "Using instance token" or "Using cached token" messages
-- ✅ Minimal "Caching new access token" messages
+No props needed - configuration comes from environment variables and your `lib/storefront.ts` file.
-### Manual Override
+## Error Handling
-You can manually control build caching:
+All SDK methods return a consistent error structure:
-```bash
-# Enable caching for this build
-NEXT_BUILD_CACHE_TOKENS=true pnpm build
+```typescript
+const { data, error, response } = await storefront(cookies()).catalog.listProducts();
-# Disable caching for this build
-NEXT_BUILD_CACHE_TOKENS=false pnpm build
+if (error) {
+  console.error("API Error:", error.message, error.code);
+  console.log("Status:", response.status);
+} else {
+  console.log("Products:", data.products);
+}
 ```
 ## Best Practices
 ### ✅ Do's
+- **Set required environment variables**: `NEXT_PUBLIC_STORE_ID` and `NEXT_PUBLIC_API_KEY` are mandatory
+- **Create one lib/storefront.ts file**: Use `createStorefront()` to configure advanced options
 - **Initialize once**: Call `StorefrontSDKInitializer` only in your root layout
 - **Use `storefront(cookies())`**: Always pass cookies in server contexts
 - **Handle errors**: Always check the error property in responses
 - **Use Server Actions**: For authentication flows that need to persist tokens
-- **Environment variables**: Store sensitive config in environment variables
 ### ❌ Don'ts
 - **Don't call `cookies()` in Client Components**: It will throw an error
 - **Don't initialize multiple times**: The SDK handles singleton behavior
 - **Don't forget error handling**: API calls can fail for various reasons
-- **Don't rely on Server Component token persistence**: They can't write cookies
+- **Don't skip environment variables**: Missing required variables will cause errors
 ## Troubleshooting
 ### Common Issues
-1. **"Cookie store passed in client environment"**
+1. **"Server context requires cookies for user continuity!"**
    ```typescript
-   // ❌ Wrong
-   storefront(cookies()) // in client component
+   // ❌ Wrong - server context without cookies (breaks user sessions)
+   storefront()
-   // ✅ Correct
-   storefront() // in client component
+   // ✅ Correct - server context with cookies
+   storefront(cookies())
+   // ✅ Root Layout exception
+   storefront({ isRootLayout: true })
    ```
-2. **"SDK not initialized"**
-   ```typescript
-   // Make sure StorefrontSDKInitializer is in your root layout
-   <StorefrontSDKInitializer config={{ ... }} />
+2. **Missing Environment Variables**
+   ```bash
+   # Ensure your .env.local has the required variables:
+   NEXT_PUBLIC_STORE_ID=your-store-id
+   NEXT_PUBLIC_API_KEY=your-api-key
    ```
-3. **"Cookies can only be modified in Server Action"**
-   This is expected behavior. Server Components can't persist tokens, but they can still make API calls with per-request tokens.
-4. **Server Environment Detection Error**
-   ```
-   🚨 Server Environment Detected!
+3. **"Cookie store passed in client environment"**
+   ```typescript
+   // ❌ Wrong - client component with cookies
+   storefront(cookies())
-   You're calling storefront() on the server without cookies.
-   Please pass the Next.js cookie store:
+   // ✅ Correct - client component without cookies
+   storefront()
+   ```
+4. **Server Actions and async cookies()**
+   ```typescript
+   // ✅ Correct - Server Actions need await cookies()
+   const sdk = storefront(await cookies());
-   ✅ Correct usage:
-   import { cookies } from 'next/headers';
+   // ✅ Server Components and API Routes use cookies() directly
    const sdk = storefront(cookies());
-   ❌ Your current usage:
-   const sdk = storefront(); // Missing cookies!
    ```
-### Debug Mode
-Enable detailed logging during development:
-```typescript
-<StorefrontSDKInitializer
-  config={{
-    storeId: "your-store-id",
-    apiKey: "your-api-key",
-    debug: true, // Enable debug logging
-  }}
-/>
-```
 ## Migration Guide
 ### From Core SDK
@@ -622,109 +597,27 @@ const sdk = new StorefrontSDK({
   storeId: "...",
   tokenStorage: new BrowserTokenStorage()
 });
-await sdk.auth.getAnonymousToken(); // Manual token creation
 // After (Next.js SDK)
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
-const sdk = storefront(cookies()); // Automatic token management
-```
-### From Previous Next.js SDK Version
-```typescript
-// Before (old pattern)
-import { getStorefrontSDK } from "@commercengine/storefront-sdk-nextjs";
-const sdk = getStorefrontSDK(cookies());
-// After (new universal pattern)
-import { storefront } from "@commercengine/storefront-sdk-nextjs";
+import { storefront } from "@/lib/storefront";
 const sdk = storefront(cookies());
 ```
-## TypeScript Support
-The SDK provides complete TypeScript support with auto-generated types:
-```typescript
-import type {
-  StorefrontSDK,
-  ApiResult,
-  UserInfo,
-  NextJSSDKConfig,
-  Environment
-} from "@commercengine/storefront-sdk-nextjs";
-// All API responses are properly typed
-const { data }: ApiResult<ProductListResponse> = await storefront(cookies()).catalog.listProducts();
-// IntelliSense works for all nested properties
-console.log(data?.products[0].name);
-```
-## User Information
-Get current user information from tokens:
-```typescript
-const sdk = storefront(cookies());
-const userInfo = await sdk.getUserInfo();
-const isLoggedIn = await sdk.isLoggedIn();
-const isAnonymous = await sdk.isAnonymous();
-const userId = await sdk.getUserId();
-const customerId = await sdk.getCustomerId();
-```
-## Advanced Usage
-### Custom Token Storage
-```typescript
-import { TokenStorage } from "@commercengine/storefront-sdk-nextjs";
-class RedisTokenStorage implements TokenStorage {
-  async getAccessToken(): Promise<string | null> {
-    // Your Redis implementation
-  }
-  async setAccessToken(token: string): Promise<void> {
-    // Your Redis implementation
-  }
-  // ... implement other methods
-}
-// Use with the core SDK directly if needed
-import { StorefrontSDK } from "@commercengine/storefront-sdk-nextjs";
-const sdk = new StorefrontSDK({
-  storeId: "your-store-id",
-  apiKey: "your-api-key",
-  tokenStorage: new RedisTokenStorage(),
-});
-```
-## Why This Wrapper Exists
-**The core SDK is powerful but complex for Next.js:**
-- Manual token storage setup and configuration
-- Server/client runtime environment handling
-- Cookie configuration for SSR/SSG
-- Request isolation and per-request instances
-- Next.js-specific execution model complexities
+## Why This Pattern?
-**This wrapper handles it all automatically:**
-- Universal `storefront()` API that works everywhere
-- Request-scoped server instances with React cache
-- Cookie-based token persistence across boundaries
-- Environment detection and configuration
-- Build-time optimizations for SSG/ISR
+**The Perfect DX Pattern provides:**
+- **One Config File**: All advanced configuration in `lib/storefront.ts`
+- **Environment Variables**: Basic config (storeId, apiKey) via env vars
+- **Universal Import**: Same `storefront()` import everywhere
+- **Strict User Continuity**: Enforces cookie passing to protect user sessions and analytics
+- **Explicit Exceptions**: Clear patterns for special cases like Root Layout
+- **Zero Guesswork**: Helpful errors guide developers to correct patterns
-**Result: Production-ready e-commerce with zero complexity!** 🚀
+**Result: Production-ready e-commerce with bulletproof user session management!** 🛡️
 ## API Reference
-For complete API documentation of all available endpoints, visit [docs.commercengine.io/api-reference](https://docs.commercengine.io/api-reference)
+For complete API documentation of all available endpoints, visit [SDK DOCS REFERENCE](https://sdk-docs.commercengine.io/sdk/)
 The Next.js SDK provides access to all the same endpoints as the core SDK: