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

package/README.md

@@ -28,24 +28,8 @@ Add your store configuration to `.env.local`:
 ```bash
 NEXT_PUBLIC_STORE_ID=your-store-id
 NEXT_PUBLIC_API_KEY=your-api-key
-```
-
-**Optional environment variables:**
-```bash
 # Environment (defaults to "staging")
 NEXT_PUBLIC_ENVIRONMENT=staging  # or "production"
-
-# Custom API endpoint (overrides environment default)
-NEXT_PUBLIC_API_BASE_URL=https://your-custom-api.example.com
-
-# Request timeout in milliseconds
-NEXT_PUBLIC_API_TIMEOUT=10000
-
-# Debug mode (defaults to false)
-NEXT_PUBLIC_DEBUG_MODE=true
-
-# Default customer group for pricing and promotions
-NEXT_PUBLIC_DEFAULT_CUSTOMER_GROUP_ID=01JHS28V83KDWTRBXXJQRTEKA0
 ```
 
 ### 2. Create Your Storefront Configuration
@@ -76,13 +60,32 @@ const storefrontConfig: StorefrontRuntimeConfig = {
   },
 };
 
-// Create the configured storefront function
+// 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..."
+};
+```
+
 ### 3. Initialize in Root Layout
 
 ```typescript
@@ -240,7 +243,7 @@ export async function GET() {
 
 ### Root Layout (Special Case)
 
-Root Layout requires explicit flag since it's outside request context:
+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
 // app/layout.tsx
@@ -268,11 +271,32 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 The SDK provides powerful build-time optimizations through intelligent token caching.
 
-### Enable Build-Time Token Caching
+### Configure Next.js for Build-Time Optimization
 
-```bash
-# Enable caching during builds
-NEXT_BUILD_CACHE_TOKENS=true pnpm build
+Create or update your `next.config.ts` (or `next.config.js`) to enable automatic token caching during builds:
+
+```typescript
+// next.config.ts
+import type { NextConfig } from "next";
+import { PHASE_PRODUCTION_BUILD } from 'next/constants';
+
+const nextConfig = (phase: string): NextConfig => {
+  const isBuild = phase === PHASE_PRODUCTION_BUILD;
+  
+  return {
+    env: {
+      // 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
+  };
+};
+
+export default nextConfig;
 ```
 
 ### SSG with generateStaticParams
@@ -334,9 +358,17 @@ With token caching enabled:
 
 ## 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.
+
 ### Anonymous Users
 
-The SDK automatically creates anonymous tokens:
+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
 // This works everywhere - creates anonymous token automatically
@@ -346,7 +378,7 @@ const { data: products } = await storefront(cookies()).catalog.listProducts();
 ### Email/Password Login
 
 ```typescript
-// Server Action
+// Server Action (✅ Recommended - can set cookies for token persistence)
 "use server";
 export async function loginUser(email: string, password: string) {
   const sdk = storefront(cookies());
@@ -365,7 +397,7 @@ export async function loginUser(email: string, password: string) {
 ### Phone/OTP Login
 
 ```typescript
-// Server Action - Step 1: Send OTP
+// Server Action - Step 1: Send OTP (✅ Recommended context)
 export async function sendOTP(phone: string, country_code: string) {
   const sdk = storefront(await cookies());
   
@@ -376,7 +408,7 @@ export async function sendOTP(phone: string, country_code: string) {
   });
 }
 
-// Server Action - Step 2: Verify OTP
+// 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());
   
@@ -571,19 +603,6 @@ import { storefront } from "@/lib/storefront";
 const sdk = storefront(cookies());
 ```
 
-### From Previous SDK Versions
-
-```typescript
-// Before (old pattern)
-import { getStorefrontSDK, storefront } from "@commercengine/storefront-sdk-nextjs";
-const sdk = getStorefrontSDK(cookies());
-const sdk2 = storefront(cookies(), { debug: true });
-
-// After (createStorefront pattern)
-import { storefront } from "@/lib/storefront"; // Your configured function
-const sdk = storefront(cookies());
-```
-
 ## Why This Pattern?
 
 **The Perfect DX Pattern provides:**
@@ -598,7 +617,7 @@ const sdk = storefront(cookies());
 
 ## 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:
 

package/dist/index.cjs

@@ -20,9 +20,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthClient: () => import_storefront_sdk3.AuthClient,
+  BrowserTokenStorage: () => import_storefront_sdk4.BrowserTokenStorage,
+  CartClient: () => import_storefront_sdk3.CartClient,
+  CatalogClient: () => import_storefront_sdk3.CatalogClient,
+  CookieTokenStorage: () => import_storefront_sdk4.CookieTokenStorage,
+  CustomerClient: () => import_storefront_sdk3.CustomerClient,
+  Environment: () => import_storefront_sdk2.Environment,
+  HelpersClient: () => import_storefront_sdk3.HelpersClient,
+  MemoryTokenStorage: () => import_storefront_sdk4.MemoryTokenStorage,
+  OrderClient: () => import_storefront_sdk3.OrderClient,
+  ResponseUtils: () => import_storefront_sdk3.ResponseUtils,
+  ShippingClient: () => import_storefront_sdk3.ShippingClient,
+  StoreConfigClient: () => import_storefront_sdk3.StoreConfigClient,
+  StorefrontAPIClient: () => import_storefront_sdk3.StorefrontAPIClient,
+  StorefrontSDK: () => import_storefront_sdk2.StorefrontSDK,
+  TokenStorage: () => import_storefront_sdk4.TokenStorage,
   createStorefront: () => createStorefront
 });
 module.exports = __toCommonJS(index_exports);
+var import_storefront_sdk2 = require("@commercengine/storefront-sdk");
+var import_storefront_sdk3 = require("@commercengine/storefront-sdk");
+var import_storefront_sdk4 = require("@commercengine/storefront-sdk");
 
 // src/sdk-manager.ts
 var import_react = require("react");
@@ -422,5 +441,21 @@ function createStorefront(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthClient,
+  BrowserTokenStorage,
+  CartClient,
+  CatalogClient,
+  CookieTokenStorage,
+  CustomerClient,
+  Environment,
+  HelpersClient,
+  MemoryTokenStorage,
+  OrderClient,
+  ResponseUtils,
+  ShippingClient,
+  StoreConfigClient,
+  StorefrontAPIClient,
+  StorefrontSDK,
+  TokenStorage,
   createStorefront
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { StorefrontSDK } from '@commercengine/storefront-sdk';
-export { StorefrontSDK } from '@commercengine/storefront-sdk';
+export * from '@commercengine/storefront-sdk';
+export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, ResponseUtils, ShippingClient, StoreConfigClient, StorefrontAPIClient, StorefrontSDK, TokenStorage } from '@commercengine/storefront-sdk';
 import { S as StorefrontRuntimeConfig } from './server-CwxgXezP.cjs';
 
 type NextCookieStore = {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { StorefrontSDK } from '@commercengine/storefront-sdk';
-export { StorefrontSDK } from '@commercengine/storefront-sdk';
+export * from '@commercengine/storefront-sdk';
+export { AuthClient, BrowserTokenStorage, CartClient, CatalogClient, CookieTokenStorage, CustomerClient, Environment, HelpersClient, MemoryTokenStorage, OrderClient, ResponseUtils, ShippingClient, StoreConfigClient, StorefrontAPIClient, StorefrontSDK, TokenStorage } from '@commercengine/storefront-sdk';
 import { S as StorefrontRuntimeConfig } from './server-CwxgXezP.js';
 
 type NextCookieStore = {

package/dist/index.js

@@ -1,3 +1,24 @@
+// src/index.ts
+import { StorefrontSDK as StorefrontSDK2, Environment as Environment2 } from "@commercengine/storefront-sdk";
+import {
+  StorefrontAPIClient,
+  AuthClient,
+  CartClient,
+  CatalogClient,
+  CustomerClient,
+  HelpersClient,
+  ShippingClient,
+  OrderClient,
+  StoreConfigClient,
+  ResponseUtils
+} from "@commercengine/storefront-sdk";
+import {
+  TokenStorage,
+  MemoryTokenStorage as MemoryTokenStorage2,
+  BrowserTokenStorage,
+  CookieTokenStorage
+} from "@commercengine/storefront-sdk";
+
 // src/sdk-manager.ts
 import { cache } from "react";
 import {
@@ -399,5 +420,21 @@ function createStorefront(config) {
   return storefront;
 }
 export {
+  AuthClient,
+  BrowserTokenStorage,
+  CartClient,
+  CatalogClient,
+  CookieTokenStorage,
+  CustomerClient,
+  Environment2 as Environment,
+  HelpersClient,
+  MemoryTokenStorage2 as MemoryTokenStorage,
+  OrderClient,
+  ResponseUtils,
+  ShippingClient,
+  StoreConfigClient,
+  StorefrontAPIClient,
+  StorefrontSDK2 as StorefrontSDK,
+  TokenStorage,
   createStorefront
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercengine/storefront-sdk-nextjs",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Next.js wrapper for the Commerce Engine Storefront SDK",
   "type": "module",
   "main": "dist/index.js",