Shopify Hydrogen v2: Complete Setup Guide from Zero to Production

## What is Shopify Hydrogen? Shopify Hydrogen is the official React-based framework for building headless Shopify storefronts. Built on top of Remix, it gives you full control over your frontend while Shopify handles the commerce backend via the Storefront API. In this guide you will go from zero to a deployed Hydrogen storefront running on Shopify Oxygen. ## Prerequisites - Node.js 18+ - A Shopify Partner account - A Shopify development store ## Step 1: Create a new Hydrogen project ```bash npm create @shopify/hydrogen@latest ``` The CLI will ask you a few questions: - **Language**: TypeScript (always pick this) - **Styling**: Tailwind CSS - **Mock data or real store**: pick your development store This scaffolds a full Hydrogen project with demo routes already wired up. ## Step 2: Connect to your Shopify store Open `hydrogen.config.ts` and set your Storefront API credentials: ```typescript import {defineConfig} from '@shopify/hydrogen'; export default defineConfig({ shopify: { storeDomain: 'your-store.myshopify.com', storefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN, storefrontApiVersion: '2024-01', }, }); ``` Get your Storefront API token from **Shopify Admin → Apps → Develop apps → your app → API credentials**. Make sure you enable the Storefront API and grant the required scopes. ## Step 3: Understanding the file structure ``` app/ routes/ # Remix file-based routing _index.tsx # Homepage products.$handle.tsx # Product pages collections.$handle.tsx components/ # Shared components lib/ # Utilities and Storefront API queries hydrogen.config.ts server.ts # Oxygen server entry ``` Hydrogen uses Remix conventions throughout. Every route file can export a `loader` for server-side data fetching and a default component for rendering. ## Step 4: Fetching data with the Storefront API Hydrogen injects a `storefront` client into every loader via the server context: ```typescript import {json} from '@shopify/remix-oxygen'; import {useLoaderData} from '@remix-run/react'; import {PRODUCT_QUERY} from '~/lib/queries'; export async function loader({params, context}: LoaderFunctionArgs) { const {storefront} = context; const {product} = await storefront.query(PRODUCT_QUERY, { variables: {handle: params.handle}, }); if (!product) throw new Response('Not found', {status: 404}); return json({product}); } ``` ## Step 5: Deploy to Shopify Oxygen Oxygen is Shopify's edge hosting platform for Hydrogen. It runs your storefront on Cloudflare Workers globally. ```bash npx shopify hydrogen deploy ``` This command: 1. Builds your Hydrogen app 2. Uploads it to Oxygen 3. Gives you a preview URL For production, link your custom domain in the Shopify admin under **Online Store → Domains**. ## Key differences from Next.js If you're coming from Next.js, the main things to know: - **Routing**: Remix file-based routing, not Next.js App Router - **Data fetching**: `loader` functions, not `getServerSideProps` or React Server Components - **Mutations**: `action` functions, not API routes - **Streaming**: Built-in via Remix `defer` and `Await` components ## Performance defaults you get for free Hydrogen includes several performance wins out of the box: - **Sub-request caching**: cache Storefront API responses at the edge - **Streaming SSR**: ship HTML progressively, skeleton UI for deferred data - **Image optimization**: `` component from `@shopify/hydrogen` with automatic sizing ## Next steps Once your base setup is running, the high-value areas to tackle next are: 1. Product page with variant selection 2. Cart implementation with optimistic UI 3. Collection page with filter and sort 4. Custom checkout integration Each of these will be covered in depth in upcoming articles.