Use this guide when the React SDK is moving from a visual shell to a real application boundary with framework-owned routing, cookie storage, locale resolution, and shopper runtime identity.

The seam names and EnadProvider props shown in this guide are verified from SDK package reference for the current docs track. Exact runtime config field shape, helper implementations, and broader framework-adapter behavior still belong to package reference. This guide stays at the integration seam: what the app should own, what the SDK expects, and where those concerns meet.

What this guide means by runtime adapters

EnadProvider is the SDK runtime boundary, but it does not replace your app framework. The SDK can render storefront, commerce, account, and Search-aware UI.

Your app still owns:

• how navigation or redirects happen.
• how auth or shopper cookies are read and written.
• how locale is resolved from route, request, or session context.
• how shopper-facing app, market, and store-group identity are resolved per request or per session.

The goal is to document those seams clearly so consumer apps do not hide framework-specific behavior inside presentational components.

The four runtime seams to decide

Not every app needs every seam on day one. A purely visual integration can stop at the stylesheet plus EnadProvider. Add the rest only when the app actually owns live behavior.

A practical provider boundary

Use one app-owned shell to gather the current framework/runtime values, then hand them to EnadProvider.

For this docs track, the seam props shown below - cookieAdapter, navigationAdapter, locale, and clientConfig - are verified public EnadProvider props. Treat getShopperRuntimeConfig() as app-owned example code rather than package API truth.

import "@enadhq/enad-react-sdk/styles.css";
import { EnadProvider } from "@enadhq/enad-react-sdk";
import {
  NextCookieAdapter,
  NextNavigationAdapter,
} from "@enadhq/enad-react-sdk/client/adapters/next";

const locale = shopper.locale;
const clientConfig = getShopperRuntimeConfig();

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider
      cookieAdapter={new NextCookieAdapter()}
      navigationAdapter={new NextNavigationAdapter()}
      locale={locale}
      clientConfig={clientConfig}
    >
      {children}
    </EnadProvider>
  );
}

Keep the example boundary in mind rather than treating the sample object names as required SDK behavior. The important decision is placement:

• framework-specific adapters are created at the app shell.
• request or session identity is resolved before rendering SDK components.
• presentational component trees consume the runtime; they do not construct it.

If your app is not on Next.js, provide the current package's framework-specific runtime adapter when one exists, or implement the same seam with your own cookie and navigation adapters.

Navigation is a redirect seam, not a full router rewrite

The current navigation seam is intentionally narrow. It exists so SDK-owned flows that need to move the shopper can use app-owned navigation behavior without importing framework internals directly.

Use navigationAdapter when the app wants SDK flows to respect its router/runtime, but keep these concerns in the app layer:

• route structure and localization.
• whether navigation is push, replace, or server redirect under the hood.
• analytics, attribution, or post-navigation tracking.
• protected-route decisions and auth gate logic.

If the route decision depends on business policy, keep that policy in the application and pass the resulting destination into SDK flows instead of teaching low-level SDK components how your router works.

Cookie access is the auth and session seam

Use cookieAdapter when account, wishlist, or other shopper flows need cookie reads or writes. The adapter seam is where the app keeps control over:

• cookie storage rules such as secure, sameSite, and path scope.
• which cookies represent shopper or auth session identity.
• framework-specific request/response cookie APIs.
• whether token state is request-scoped, browser-scoped, or both.

Do not push cookie behavior down into cart buttons, drawers, or form components. Those surfaces should consume already-wired runtime behavior from the provider tree.

Locale is a value seam, not a framework adapter

Locale is simpler than navigation or cookies, but it is still a runtime boundary.

Pass locale from the same app-owned context that chooses the current shopper experience. That usually means route, request, or session state rather than a repo-level constant.

Keep locale aligned across:

• EnadProvider locale=\{...\}.
• shopper-facing runtime config defaults such as Search context.
• route state for market and store group.
• price formatting and Search-backed display surfaces.

If a page shows the wrong currency language or Search context, debug the app-owned locale and market/store-group resolution first before changing presentational SDK components.

Runtime session identity should stay request-scoped or session-scoped

The SDK expects shopper-facing runtime identity to be passed in, not discovered from static repo configuration.

Good inputs for that identity are:

• tenant or app metadata resolved during request setup.
• signed shopper session data.
• current market/store-group selection.
• request-scoped integration config already owned by the host app.

Keep server secrets out of client props. EnadProvider is the shopper-facing boundary.

Two related rules help keep responsibilities clean:

• auth/session cookie mechanics belong with the cookieAdapter.
• cart session mechanics belong inside the chosen cart adapter.

That separation keeps the runtime shell understandable: the provider receives shopper-facing seams, while each adapter owns its own backend-specific session details.

When to add runtime adapters

Add these seams when:

• the app already has real auth or shopper cookie behavior.
• SDK flows need framework-aware redirects.
• Search or storefront identity changes by market, locale, or store group.
• the same React shell runs across more than one shopper context.

Wait on them when:

• the page is still a purely visual prototype.
• the app has not chosen its auth/session policy yet.
• cart, search, or account behavior is still being mocked at the page layer.

Related routes

• React SDK setup.
• Import surfaces.
• Cart adapters.
• Product listing and search.
• React SDK latest.