Framework guides

@productgenius/react is plain React — it renders the same everywhere. What differs between frameworks is only the surrounding wiring: where your product data comes from, how you run your cart mutation, and how you generate a CSP nonce. Everything else — props, CSP hosts, theming, testing — is identical across all of them.

Coverage, honestly

The framework guides are not all equally battle-tested, and it matters when you are budgeting time. Three tiers:

Maintained, tested reference — Hydrogen is the one kept as a real, tested reference: a git apply-able diff against a fresh Hydrogen skeleton, the post-integration version of every file the integration touches, and the handoff bundle built from it. It ships in your Product Genius handoff as productgenius-react-integration.tar.gz.

Verified reference files — the plain React (Vite) and TanStack Start guides are mostly quickstarts, but each carries real files from a scaffolded app that was actually built and booted against this package: the render component and Vite config for plain React; the route, the server function, and the Vite config for TanStack Start. Copy them, or diff them against your own.

Quickstart guide — the Next.js and React Router guides are the same integration shape written idiomatically for each framework, but they are not maintained as scaffolded, tested apps. If you hit a framework-specific snag one of them doesn't cover, your Product Genius contact can help work through it.

The guides themselves live alongside the package source under examples/<framework>/; the Hydrogen reference also travels in the handoff bundle. Ask your Product Genius contact if you need one you can't see.

Not on any of these? The component doesn't care — <ProductGeniusFeed> works anywhere React 18 or 19 renders on your storefront's frontend.

What is framework-specific

Install is the same everywhere (one page). These are the parts that differ.

Shopify Hydrogen

• CSP — Hydrogen's createContentSecurityPolicy() in app/entry.server.tsx is where the Product Genius hosts go, and its useNonce() hook is what you pass to the nonce prop.
• Cart — onAddToCart goes through Hydrogen's CartForm (LinesAdd) submitted to the /cart action, then opens the cart aside. This is where the numeric-id-to-gid mapping lives.
• Vite — Hydrogen runs on Vite, so it needs the optimizeDeps pre-bundle.
• The reference integration touches exactly three files (app/routes/products.$handle.tsx, app/entry.server.tsx, vite.config.ts); the dependency itself comes from your install, not from the diff.
• Remix v2 Hydrogen — identical wiring; only two imports differ (react-router → @remix-run/react, and the loader-args type from @shopify/remix-oxygen). The component, cart wiring, CSP, and Vite line carry over unchanged.

Plain React (Vite)

• Client-only: there is no server framework, so the cart mutation runs in the browser (direct GraphQL/REST, a wrapper client, or your own hook).
• CSP comes from your hosting platform's headers or a <meta http-equiv> tag rather than a per-request nonce — omit the nonce prop unless your host injects a nonce-based policy.
• Vite — needs the optimizeDeps pre-bundle.

Next.js (App Router)

• The built package carries "use client", so a Server Component page can import and render <ProductGeniusFeed> directly — no wrapper client component needed.
• Cart — a Server Action is the idiomatic onAddToCart. Note that a Server Action cannot update client-side cart UI (a drawer, a badge count) on its own: pair it with your existing client cart state, or call the mutation from a Route Handler if you need an immediate optimistic update.
• CSP — generate the nonce in proxy.ts (named middleware.ts on versions before the Proxy rename), forward it on a request header, read it with headers(), and pass it to the nonce prop. proxy.ts runs only on the nodejs runtime; if you need edge, stay on middleware.ts.
• No Vite caveat — Next.js doesn't use Vite, so the optimizeDeps pre-bundle doesn't apply. See the install page for the Turbopack resolution caveat that does.

React Router (framework mode)

• Routing — framework mode does not do filename-based routing by default. Register your product and cart routes explicitly in app/routes.ts or the paths 404.
• Cart — onAddToCart submits to a route action via useFetcher.
• CSP — you set headers in app/entry.server.tsx. The default scaffold does not ship one; write it, or run npx react-router reveal entry.server first to materialize the CLI's default and edit that. The nonce is generated in the same render pass as your route components, so it cannot travel through loader data — thread it through React context (wrap <ServerRouter> in your own provider and read it with a small useNonce() hook). Hydrogen implements exactly this pattern for you; here you add it yourself.
• Vite — needs the optimizeDeps pre-bundle.

TanStack Start

• Routing — file-based; the route tree regenerates on dev/build, so there is no route-tree file to hand-edit.
• Cart — onAddToCart calls a server function created with createServerFn from @tanstack/react-start.
• CSP — set headers from your server entry as you would for any SSR framework: per-request nonce, added to script-src, passed to the nonce prop.
• Vite — TanStack Start runs on Vite, so it needs the optimizeDeps pre-bundle.