ShopGPT is a Shopify Hydrogen storefront that pairs a clean shopping UI with AI-assisted search and an Ask Shopper assistant. It is built on React Router 7 (Hydrogen’s current stack), not Remix.
Shopify Hydrogen docs · React Router
| Area | What it does |
|---|---|
| Homepage | Centered hero, AI search bar, featured product carousels, optional subtle cursor glow scoped to the main column. |
| Ask Shopper | Side panel “ShopGPT assistant” that runs searches in-context and surfaces product-style replies using the same search pipeline as the main search page. |
| Search & analytics | Full search with AI intent extraction, deferred summaries, predictive dropdown, and a Search History view with period filters (today / week / month / 6 months), interactive charts (Recharts, client-only), and term frequency—backed by localStorage (no separate analytics backend). |
| Checkout | Standard Hydrogen + Shopify flow: cart, checkout handoff via Storefront/checkout GraphQL patterns and shop.app / checkout domain integration. Customer account area for orders, profile, and addresses. |
- Gradient hero headline and subtitle
- AISearchBar with predictive product hints
- Two FeaturedCarousel sections (trending / reversed list)
- HomeCursorGlow — optional pointer-follow glow (homepage background only; not over sidebar or Ask Shopper)
- CursorTrail — physics-style product image trail exists in the codebase but is commented out in
app/routes/_index.jsx(easy to re-enable)
- Fixed trigger opens a shopper sidebar with chat-style UI
- Submits user messages and loads same-origin search results via the app’s search route
- Cart, search aside, and layout live in
app/components/PageLayout.jsxandapp/components/AskShopperPanel.jsx
- AI search (
app/routes/search.jsx,app/lib/ai.server.js): Storefront search plus OpenAI for intent + optional result summary - Predictive search: client
fetchto/search?q=…&predictive - Search History: toggle on the search page; chart module
SearchHistoryChartPanelis dynamically imported so Recharts does not run under SSR (avoids MiniOxygen/Vite issues)
- Cart drawer and checkout links follow Hydrogen patterns
- Proxy route
app/routes/api.$version.[graphql.json].jsxforwards to Shopify checkout GraphQL onPUBLIC_CHECKOUT_DOMAIN - Customer Account API routes under
/account(orders, profile, addresses, OAuth helpers)
| API / service | Role |
|---|---|
| Shopify Storefront API (GraphQL) | Products, collections, cart, search, predictive search, blogs, pages, policies, menus, etc. (context.storefront) |
| Shopify Customer Account API (GraphQL) | Logged-in customer, orders, profile, addresses (context.customerAccount) |
| OpenAI API | Chat Completions (gpt-4o-mini) for search intent extraction and short result summaries (OPENAI_API_KEY) |
| Shopify checkout GraphQL | Proxied through /api/:version/graphql.json → https://<PUBLIC_CHECKOUT_DOMAIN>/api/.../graphql.json |
| Browser localStorage | Search history for the analytics view (not sent to a server) |
| Shopify CDN | Product and store imagery (cdn.shopify.com) |
| Google Fonts | Inter (loaded from fonts.googleapis.com) |
Internal (same app, not third-party): fetch / useFetcher to /search for predictive search and Ask Shopper.
- Hydrogen 2026.x, React 18, React Router 7
- Vite 6, Shopify CLI / Oxygen-style local dev (MiniOxygen)
- GraphQL + generated types (
storefrontapi.generated.d.ts,customer-accountapi.generated.d.ts) - OpenAI official Node SDK
- Recharts (search history chart, client-only chunk)
- ESLint, Prettier
- Node.js
^22 || ^24(seepackage.jsonengines)
npm install
npm run devCopy .env from your Shopify / Hydrogen project template and set at least:
SESSION_SECRET- Storefront API credentials (per Hydrogen docs)
OPENAI_API_KEY(optional but required for AI search intent + summaries)PUBLIC_CHECKOUT_DOMAINand related checkout vars as in your Shopify dashboard
npm run build # production build
npm run preview # preview production build locallyRecommended (production): Use Shopify Hydrogen on Oxygen. This app’s server.js is an Oxygen-style Worker (fetch handler with Hydrogen context). npm run dev runs Mini Oxygen, which is why the storefront matches production on Shopify’s hosting.
Vercel: Hydrogen is not wired for Vercel’s first-party React Router preset. That preset assumes @vercel/react-router and a different build/runtime shape; Hydrogen’s hydrogenPreset() conflicts with that adapter (e.g. serverBundles / buildEnd).
When connecting this repo to Vercel:
- Set the framework preset to Other (not React Router), or rely on
vercel.json(framework: null) so the dashboard does not default to abuild/output folder. - In Build & Development Settings, either turn off overrides for build/output so
vercel.jsonwins, or set Output Directory todist/clientand Build Command tonpm run buildexplicitly. - Redeploy. The build should complete without
ENOENT ... 'build'; the live URL may still show Vercel’s404: NOT_FOUNDat/— that is expected for this setup (see below).
Limitation: Publishing only dist/client serves static assets; there is no index.html at the root—HTML is produced by SSR via the Worker in server.js. Vercel is not running that Worker, so the public site will not match localhost:3000. For production, deploy to Oxygen (requires Shopify CLI login and a linked Hydrogen storefront):
npm run deployUse Shopify’s Hydrogen deployment docs to connect GitHub and environment variables in the Shopify admin.
For OAuth and account routes in development, follow Shopify’s public-domain steps:
Initial ShopGPT build: less than one day (Hydrogen scaffold, UI shell, AI search, Ask Shopper, search history analytics, cursor effects, and SSR fixes such as client-only Recharts loading).
This repo includes .cursor/rules/hydrogen-react-router.mdc: use React Router imports, not Remix or react-router-dom, when extending the app.