@commercengine/storefront-sdk-nextjs 0.2.10 → 0.3.1

package/MIGRATION.md

@@ -0,0 +1,89 @@
+# Storefront SDK Next.js Migration Guide
+
+This guide covers the breaking API changes in
+`@commercengine/storefront-sdk-nextjs`.
+
+## Summary
+
+- `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()`
+
+## Before / After
+
+### Public server reads
+
+Before:
+
+```typescript
+const sdk = storefront({ isRootLayout: true });
+const { data } = await sdk.catalog.listProducts();
+```
+
+After:
+
+```typescript
+const sdk = storefront.public();
+const { data } = await sdk.catalog.listProducts();
+```
+
+### Server components, server actions, and route handlers
+
+Before:
+
+```typescript
+const sdk = storefront(await cookies());
+```
+
+After:
+
+```typescript
+const sdk = storefront.session(await cookies());
+```
+
+### Client components
+
+Before:
+
+```typescript
+const sdk = storefront();
+```
+
+After:
+
+```typescript
+const sdk = storefront.session();
+```
+
+## New Mental Model
+
+Use `storefront.public()` for:
+
+- root layouts
+- static generation
+- ISR pages
+- public server-rendered catalog or helper reads
+
+Use `storefront.session()` / `storefront.session(await cookies())` for:
+
+- 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
+
+## Root Layouts
+
+There is no special root-layout escape hatch anymore.
+
+Root layouts should:
+
+- use `storefront.public()` for public reads
+- mount `StorefrontSDKInitializer` to eagerly bootstrap the browser session
+
+If a server component needs request-bound session continuity, move that call to a
+request-aware boundary and use `storefront.session(await cookies())`.