Start here when wiring @enadhq/enad-react-sdk into a React app for the first time, or when checking whether an existing app shell has the right runtime boundaries.

Exact package versions, provider option names, component props, hooks, helper signatures, and package runtime behavior belong to SDK package reference. This guide gives the safe setup order and only uses confirmed public imports in copy-paste snippets.

Setup order

A reliable React SDK shell is built in this order:

1. Install the package version for the current React SDK docs track.
2. Import the SDK stylesheet once from the app's global CSS entry or root shell.
3. Put EnadProvider at the app runtime boundary.
4. Use EnadProvider componentSet=\{...\} for app-wide structural set selection.
5. Add EnadThemeProvider inside EnadProvider only when a subtree needs hash restoration or scoped token/theme state.
6. Add client, Search, cart, and account/auth integrations only after the app owns those boundaries and has confirmed the exact package option shape.
7. Verify route rendering, styling, provider context, theme state, Search context, and auth/session behavior before building feature pages on top.

Use Runtime adapters when framework-owned routing, cookies, locale, or shopper identity need to cross the provider boundary. Open Account and auth UI when the shell is ready for login, signup, password, and sign-out flows. Choose Cart adapters when the shell is ready for live cart behavior.

Install and import the stylesheet

Install @enadhq/enad-react-sdk using the package version documented by the current package-react-sdk track. Then import the stylesheet once.

import "@enadhq/enad-react-sdk/styles.css";

Put that import where your app already imports global CSS. If SDK components render but look unstyled, confirm this import is loaded by the route before changing component code or theme state.

Place the root provider

EnadProvider is the root SDK runtime provider. Put it at the boundary that wraps pages using SDK components and owns SDK-wide runtime behavior.

import { EnadProvider } from "@enadhq/enad-react-sdk";

export function AppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider>{children}</EnadProvider>;
}

Start with the provider shell before adding options. Add provider options only when the application has the corresponding integration ready and you have checked the current package reference for the exact option names.

Do not copy live playground internals, sandbox helpers, or generated demo wiring into a consumer app. The playground is useful for runtime validation; its internal setup is not the consumer setup contract.

Add theme state only when it has a job

EnadProvider already owns the app-wide SDK runtime and can select a structural component set for the whole tree.

import { EnadProvider } from "@enadhq/enad-react-sdk";

export function ThemedAppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider componentSet="editorial">{children}</EnadProvider>;
}

Add EnadThemeProvider inside EnadProvider when a subtree needs a restored playground hash, scoped token overrides, or a nested theme boundary. Confirm the current package reference before relying on any exact prop shape beyond the documented theme-provider model.

import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";

const themeHash = "paste-playground-theme-hash-here";

export function RestoredThemeShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider>
      <EnadThemeProvider hash={themeHash}>{children}</EnadThemeProvider>
    </EnadProvider>
  );
}

Theme precedence is explicit EnadThemeProvider props, then decoded hash values, then SDK defaults. An app-wide EnadProvider componentSet is structural too: it changes the selected UI family, rather than only colors.

Add connected integrations only when the app owns them

A visual page can start with the stylesheet and providers above. Connected behavior needs app-owned runtime integrations.

• Add client configuration when SDK components or helpers need live API access.
• Add Search configuration when autocomplete, search results, recommendations, or Search-backed product wrappers need live Search GraphQL data.
• Add account/auth UI after cookie, navigation, and shopper-session seams are wired at the app boundary.
• Add cart configuration when the app owns cart state and side effects.

Use Runtime adapters to keep navigation, cookies, locale, and shopper runtime identity at the provider boundary. Open Account and auth UI when the application is ready to place login/signup/password/sign-out UI on the public client/user surface. Choose Cart adapters when comparing the shipped Brink adapter, mock adapter, or a custom CartAdapter.

This guide does not show placeholder provider option objects. Copying invented shapes creates brittle setup code. Use package reference for the exact option names, then keep those options at the same root provider boundary rather than hiding them inside presentational components.

Keep Search context consistent

Provider-backed Search runtime keeps market, store group, and locale together. Use the same context across:

• provider-backed Search runtime configuration
• Search GraphQL variables
• route state such as market, store group, locale, query, filters, and sort
• product mapping into display cards

Current package behavior to preserve:

• graphql.storeGroupSlug can override groupId for Search context.
• mapSearchProductToProductCard() accepts storeGroupSlug so mapped product cards can prefer the intended store-group price.

If a Search page shows prices, availability, facets, or translations from the wrong context, debug the market/store-group/locale values before changing UI components. Exact Search query shape, fields, generated documents, hooks, and helper imports remain Search schema and package reference truth.

Verification and troubleshooting checklist

Before debugging individual components, check the setup boundary first:

1. The app imports @enadhq/enad-react-sdk/styles.css once and the route actually loads it.
2. SDK components render under EnadProvider.
3. EnadThemeProvider, when used, is nested inside EnadProvider.
4. App-wide component-set choices, theme hashes, and explicit token overrides are not fighting the intended precedence.
5. Live Search pages provide package-verified client/search configuration at the root runtime boundary.
6. Search market, store group, and locale match between provider context, GraphQL variables, route state, and product mapping.
7. Cart and checkout side effects remain in the app's commerce integration, not in presentational product cards.
8. Exact prop names, hook names, GraphQL fields, and helper imports are checked against package reference before code is committed.

For symptom-based recovery, use Troubleshooting.

Next routes

• First React SDK app for the first page after the shell works.
• Runtime adapters for navigation, cookies, locale, and shopper runtime identity.
• Account and auth UI and Cart adapters for connected commerce state.
• Theme from playground and React SDK theming for theme hashes, component sets, and runtime theme state.
• Product listing and search and Search GraphQL latest for Search-backed pages.