Ce Ssr Patterns

LLM Docs Header: All requests to https://llm-docs.commercengine.io must include the Accept: text/markdown header (or append .md to the URL path). Without it, responses return HTML instead of parseable markdown.

SSR / Meta-Framework Patterns

For basic installation, see setup/. For the rarer case where you need custom request-bound SSR bindings with @commercengine/ssr-utils (Nuxt or other unsupported frameworks), see ssr/.

This skill covers frameworks with first-party Commerce Engine wrappers: Next.js, TanStack Start, Astro, and SvelteKit. All ship as subpath exports of @commercengine/storefront.

Impact Levels

• CRITICAL - Session continuity bugs, auth bugs
• HIGH - Common mistakes
• MEDIUM - Performance or maintainability issues

References

Shared Mental Model

All first-party SSR wrappers follow the same three-accessor pattern (Next.js, TanStack Start, Astro, SvelteKit):

Bootstrap

SSR apps must call storefront.bootstrap() on the client (root layout mount) before later serverStorefront() reads depend on cookie continuity. Without it, session continuity is not guaranteed. See each framework's reference for the exact bootstrap pattern.

Pre-rendering for SEO & Initial Load

Use publicStorefront() in route loaders (TanStack Start) or generateStaticParams / Server Components (Next.js) to pre-render catalog pages. This gives you excellent SEO and fast initial page loads:

// Route loader (TanStack Start) or Server Component (Next.js)
const sdk = storefront.publicStorefront();
const { data } = await sdk.catalog.listProducts({ limit: 100 });

publicStorefront() never creates sessions, never reads/writes cookies, and is safe for build-time, pre-render, and ISR contexts.

Client-Side Fetching After Hydration

Once the app is hydrated, client-side fetching is equally fast and much less complex. There is no need to wrap SDK calls in server functions — the SDK talks to a public API with no secrets to protect. Use React Query (or any fetching library) directly:

// Public reads — no session needed
const sdk = storefront.publicStorefront();
const { data } = await sdk.catalog.listProducts({ limit: 20 });

// Session-bound reads (cart, wishlist, account) — use client accessor
const sessionSdk = storefront.clientStorefront();
const { data: wishlist } = await sessionSdk.cart.getWishlist();

The session-aware overloads resolve user_id automatically — no manual ID passing needed.

Framework Quick Reference

All imports above are subpaths of @commercengine/storefront. See the framework-specific reference for full setup, accessor rules, patterns, and examples.

Hosted Checkout + SSR

When using Hosted Checkout with an SSR framework, the Storefront SDK remains the session owner. Wire onTokensUpdated in the storefront config so checkout stays in sync on the client side:

// In storefront config (both frameworks)
onTokensUpdated: (accessToken, refreshToken) => {
  if (typeof window !== "undefined") {
    void import("@commercengine/checkout").then(({ getCheckout }) => {
      getCheckout().updateTokens(accessToken, refreshToken);
    });
  }
},

Then initialize checkout in the bootstrap/initializer component after storefront.bootstrap() completes. No provider wrapper needed — initCheckout is called once and useCheckout() works globally.

Callback signature difference: The SDK's onTokensUpdated receives two separate arguments (accessToken, refreshToken). Checkout's onTokensUpdated receives a single object ({ accessToken, refreshToken }). Do not mix these up.

useEffect(() => {
  const init = async () => {
    await storefront.bootstrap();

    const sdk = storefront.clientStorefront();
    const accessToken = await sdk.getAccessToken();
    const refreshToken = await sdk.session.peekRefreshToken();

    initCheckout({
      storeId: /* ... */,
      apiKey: /* ... */,
      authMode: "provided",
      accessToken: accessToken ?? undefined,
      refreshToken: refreshToken ?? undefined,
      onTokensUpdated: ({ accessToken, refreshToken }) => {
        void sdk.setTokens(accessToken, refreshToken);
      },
    });
  };
  void init();
  return () => destroyCheckout();
}, []);

Common Pitfalls (All SSR Frameworks)

See Also

• setup/ - Basic SDK installation and framework detection
• ssr/ - Custom SSR bindings with @commercengine/ssr-utils (Nuxt and other unsupported frameworks)
• auth/ - Authentication flows
• cart-checkout/ - Cart and Hosted Checkout patterns

Documentation

• SDK Documentation: https://www.commercengine.io/docs/sdk
• LLM Reference: https://llm-docs.commercengine.io/sdk/