Hydrogen SEO: Shopify's React framework, Oxygen, headless commerce

A comprehensive installation and audit reference for Shopify Hydrogen as a headless storefront framework. Hydrogen is Shopify's React based framework for building headless storefronts, positioned for…

The Canonical 2026 Reference for Shopify Hydrogen Headless Storefronts: Remix Architecture, Oxygen Deployment, Self Hosted Node.js Alternatives, Storefront API Integration, Schema in Hydrogen Routes, International Routing, and Migration Discipline

A comprehensive installation and audit reference for Shopify Hydrogen as a headless storefront framework. Hydrogen is Shopify's React based framework for building headless storefronts, positioned for merchants outgrowing Online Store themes who want full control over rendering while keeping Shopify's checkout, catalog, and order management. Hydrogen 2 runs on Remix at the routing layer, the Storefront API at the data layer, and Oxygen or any Node.js host at the runtime layer.

Cross stack implementation note: this is the canonical Hydrogen reference. For the underlying Shopify platform see framework-shopify.md. For schema patterns see framework-schema.md. For headless CMS context see framework-headless.md. For client rendered React see framework-react.md. For migration see framework-migration.md. For Core Web Vitals see framework-pageexperience.md. For international routing see framework-international.md and framework-hreflang.md. For AI surface see framework-aicitations.md.

1. Document Purpose

Hydrogen is Shopify's answer to a specific merchant pain point: the Online Store theme is sufficient for most stores but limiting for stores that need bespoke rendering, deep content integration, or brand distinctive design the OS 2.0 theme system cannot support. Hydrogen offers full React with Remix routing while preserving Shopify's checkout, catalog, customer accounts, and order management.

The SEO implications differ significantly from native Shopify. Native Shopify gives a constrained URL structure, automatic Product and BreadcrumbList schema in OS 2.0, automatic image optimization via the Shopify CDN, automatic canonical handling, and a fast platform edge. Hydrogen gives total control over all of those surfaces. Total control is a benefit when the engineering team executes well and a liability when the team ships missing canonicals, broken hreflang clusters, and bloated client bundles.

1.1 When to Recommend Hydrogen

Hydrogen fits: merchants at 2M USD annual GMV and up, React engineering capacity in house or via long term agency, brand distinctive storefront design requirements the OS 2.0 theme system cannot support, content heavy stores wanting deep CMS integration, performance critical contexts where the Online Store theme baseline is not enough, multi country setups where Markets does not give sufficient routing control.

Hydrogen does not fit: stores under 1M USD annual GMV (engineering investment rarely amortizes), merchants without engineering capacity, stores wanting to remain in the Shopify App Store ecosystem (most apps target the native theme architecture and do not work on Hydrogen), stores with a simple catalog and standard checkout where the OS 2.0 Dawn theme is already sufficient.

The crossover GMV point in 2026 is approximately 2M USD for differentiated brand stores, 5M USD for commodity catalog stores. Below those thresholds, the Online Store theme almost always wins on total cost. The deciding factor is rarely SEO; it is brand differentiation, custom rendering needs, and engineering capacity.

1.2 Hydrogen vs Native Shopify vs Other Headless Patterns

1.3 Operating Modes

Mode A, Install. New Hydrogen storefront. Follow Sections 2 through 14 in order. Mode B, Audit. Existing Hydrogen storefront. Skip to Section 11 audit rubric. Mode C, Migrate from Theme. Native Shopify theme to Hydrogen. Skip to Section 11. Mode D, Migrate from Other Headless. Next.js Commerce or similar to Hydrogen. Skip to Section 13.

1.4 Required Tools

Shopify admin (Plus recommended), Hydrogen storefront app with Storefront API tokens, Node.js 20 or 22 LTS, Git, Oxygen access or alternative host credentials, Google Search Console, Google Merchant Center, PageSpeed Insights, Lighthouse, a staging environment.

2. Client Variables Intake

Stored at /var/www/sites/[domain]/audit/hydrogen/intake.yaml.

# HYDROGEN SEO CLIENT VARIABLES

business_name: ""
primary_domain: ""
shopify_subdomain: ""
shopify_plan: ""                              # advanced, plus
launch_date: ""
gmv_annual_usd: 0
project_phase: ""                             # design, build, launch, audit

# Hydrogen version and runtime
hydrogen_version: ""                          # e.g. 2025.4.0
remix_version: ""
vite_version: ""
node_runtime_target: ""                       # oxygen, node_20, node_22
react_version: ""
typescript_used: true

# Deployment
deployment_target: ""                         # oxygen, vercel, netlify, self_hosted_node
custom_domain_configured: false
preview_environment_present: true

# Routing
url_prefix_scheme: ""                         # shopify_compatible, custom
trailing_slash_policy: ""                     # always, never, redirect
locale_routing: ""                            # none, subpath, subdomain
locale_list: []
canonical_strategy: ""                        # per_route, layout_default

# Catalog scale
total_products: 0
total_variants: 0
total_collections: 0
total_articles: 0
total_pages: 0

# Storefront API
storefront_api_version: ""                    # e.g. 2025-04
storefront_api_token_scope: ""                # public, private

# Customer Account API
customer_account_api_enabled: false
gated_content_present: false

# Performance baseline
lcp_mobile_p75: 0
inp_mobile_p75: 0
cls_mobile_p75: 0
javascript_bytes_p75: 0
lighthouse_mobile_perf: 0
lighthouse_mobile_seo: 0

# Schema state
product_schema_present: false
collection_schema_present: false
organization_schema_present: false
breadcrumb_schema_present: false
schema_graph_pattern_used: false

# International
international_active: false
hreflang_present: false
hreflang_method: ""

# Migration history
previous_platform: ""
migration_date: ""
url_mapping_documented: false

# AI surface
appears_in_aio_for_brand: false
appears_in_perplexity_for_brand: false
appears_in_chatgpt_search_for_brand: false

The intake is gating. Audit and optimization work cannot run cleanly without it.

3. Hydrogen Platform Overview 2026

Hydrogen has been through three architectural revisions since launch.

3.1 The Hydrogen Generations

Hydrogen 1. Launched 2021, used React Server Components with bespoke file based routing. Discontinued for new builds in 2023. Existing Hydrogen 1 storefronts should be migrated to Hydrogen 2.

Hydrogen 2. Launched late 2023, rebuilt on Remix as the routing and data layer. Rendering model is standard SSR with selective client hydration; RSC is no longer the default.

Hydrogen 2 plus Vite migration. In 2024 Shopify migrated build tooling from Remix's bundler to Vite. Runtime semantics remained Remix. All new Hydrogen storefronts use Remix on Vite. Shopify's late 2025 roadmap signaled possible future alignment with React Router 7 but no public timeline; for 2026 builds, assume Remix conventions stable.

3.2 The Remix Foundation

Every route file in app/routes/ exports a default React component plus optional loader (server side data fetching), action (form submissions and mutations), meta (meta tags), headers (HTTP response headers), and links (preload and stylesheet tags) functions.

// app/routes/products.$handle.tsx
import {json, type LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';
import type {MetaFunction} from '@remix-run/react';

export async function loader({params, context}: LoaderFunctionArgs) {
  const {handle} = params;
  const {product} = await context.storefront.query(PRODUCT_QUERY, {variables: {handle}});
  if (!product) throw new Response('Not Found', {status: 404});
  return json({product});
}

export const meta: MetaFunction<typeof loader> = ({data}) => {
  if (!data) return [];
  const {product} = data;
  return [
    {title: `${product.title} | Acme`},
    {name: 'description', content: product.description?.slice(0, 155)},
    {tagName: 'link', rel: 'canonical', href: `https://example.com/products/${product.handle}`},
    {property: 'og:title', content: product.title},
    {property: 'og:image', content: product.featuredImage?.url},
  ];
};

export default function Product() {
  const {product} = useLoaderData<typeof loader>();
  return <article><h1>{product.title}</h1></article>;
}

The loader and meta functions run on the server. Meta tags appear in initial HTML. Crawlers see complete meta in the initial response.

3.3 The Storefront API

Shopify's public read GraphQL API for storefront facing data: products, collections, articles, pages, customer accounts, cart, checkout. Authentication via a public Storefront API token scoped to the headless surface.

Rate limits in 2026: Plus tier allows 1,000 calls per minute per IP per store. Lower plans cap at 60 calls per minute. Hydrogen's caching layer absorbs most of this; uncached query bursts under high traffic can hit the limit on lower plans.

The Storefront API version is pinned per Hydrogen storefront. Current stable as of 2026 is 2025-04. Shopify supports four versions in parallel; storefronts have approximately one year to migrate before a version sunsets. Tokens supplied via environment variables; never hard coded.

3.4 Oxygen as the Default Runtime

Oxygen is Shopify's serverless runtime for Hydrogen storefronts. It runs on Shopify's global edge with deployment via npm run deploy from the merchant's repository. SSL, image delivery via the Shopify CDN, environment variables, and routing handled by Oxygen.

Performance baseline on Oxygen in 2026: TTFB consistently under 200 milliseconds globally. The edge proximity gives Hydrogen storefronts a measurable advantage over Online Store themes on first byte.

Oxygen does not run on arbitrary cloud providers. Merchants who want sovereignty deploy to alternative runtimes.

3.5 Alternative Runtimes

Hydrogen is a Remix application. Remix runs anywhere Node.js runs. Common targets: Vercel (native Remix support, edge functions), Netlify (Remix adapter), AWS Lambda plus CloudFront (higher operational burden), self hosted Node.js behind nginx (Section 14). The Storefront API and Shopify CDN are accessible from anywhere; the runtime choice does not affect catalog access or image delivery, only performance, operational model, and cost.

3.6 The React Server Components Question

Hydrogen 1 used RSC. Hydrogen 2 does not. For SEO this is a non issue. SSR with Remix produces the same observable behavior as RSC from a crawler's perspective: full HTML at first byte, JavaScript shipping to the client for interactivity.

4. SSR vs ISR vs CSR Decision

Hydrogen defaults to server side rendering. This is the correct choice for SEO.

4.1 SSR (Default)

Every page request triggers loader execution on the server. The loader fetches data from the Storefront API. The route component renders to HTML using the loader data. The HTML response includes complete meta tags, schema, content, and links. The client then hydrates for interactivity.

This is the rendering model for all product pages, collection pages, search results, and personalized routes. Crawlers receive complete HTML on first byte.

4.2 Static Generation Use Cases

For Hydrogen, static generation makes sense for marketing pages (/about, /our-story, /sustainability), blog landing pages with infrequent updates, FAQ pages, legal pages, the homepage when editorially curated and infrequently changed.

It does not make sense for product pages (inventory and price change frequently), collection pages (membership and sort order change), search results, cart, account, or checkout.

When a Hydrogen route is effectively static, cache the SSR output aggressively via cache headers and let the runtime cache serve cached HTML.

// app/routes/about.tsx
export const headers = () => ({
  'Cache-Control': 'public, max-age=300, s-maxage=86400, stale-while-revalidate=604800',
});

The s-maxage=86400 tells the caching layer to retain rendered output for 24 hours. Combined with stale-while-revalidate, the page serves from cache instantly while regenerating in the background.

4.3 Streaming Pattern for Product Pages

Remix supports defer for loader data, returning a streamed response where critical data renders immediately and slower data streams in. For product pages, this enables a fast first contentful paint while related products or reviews stream in.

import {defer, type LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {Suspense} from 'react';
import {Await, useLoaderData} from '@remix-run/react';

export async function loader({params, context}: LoaderFunctionArgs) {
  const product = await context.storefront.query(PRODUCT_QUERY, {variables: {handle: params.handle}});
  const recommendations = context.storefront.query(RECOMMENDED_QUERY, {variables: {handle: params.handle}});
  return defer({product, recommendations});
}

export default function Product() {
  const {product, recommendations} = useLoaderData<typeof loader>();
  return (
    <>
      <h1>{product.title}</h1>
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Await resolve={recommendations}>
          {(data) => <Recommendations products={data.products} />}
        </Await>
      </Suspense>
    </>
  );
}

Critical product data (title, description, price, availability) renders in the initial HTML. Recommendations stream in after. Crawlers see streamed content because Hydrogen waits for the stream to complete before closing the response on bot requests when bot detection middleware is in place.

4.4 The Never CSR Rule for Indexable Routes

Routes that need to rank must render on the server. The temptation to client fetch via useEffect for product specs, reviews, or recommendations must be resisted for any content that contributes to ranking signals.

The exception is data that is genuinely personalized: cart contents, customer specific pricing on B2B routes, account dashboards. The SSR shell renders a generic version; the personalized layer hydrates after authentication.

Client only data fetching for indexable content is the most common Hydrogen SEO failure mode encountered in audits. Always check that schema, descriptions, and structured data render in the SSR response.

5. The Hydrogen SEO Setup

5.1 The Meta Function Pattern

Every route can export a meta function returning an array of meta descriptors for title, description, canonical, Open Graph, Twitter Cards, and arbitrary additional tags.

import type {MetaFunction} from '@remix-run/react';

export const meta: MetaFunction<typeof loader> = ({data}) => {
  if (!data?.product) return [];
  const {product} = data;
  const canonicalUrl = `https://example.com/products/${product.handle}`;
  return [
    {title: product.seo?.title || `${product.title} | Acme`},
    {name: 'description', content: product.seo?.description || product.description?.slice(0, 155)},
    {tagName: 'link', rel: 'canonical', href: canonicalUrl},
    {property: 'og:type', content: 'product'},
    {property: 'og:title', content: product.title},
    {property: 'og:image', content: product.featuredImage?.url},
    {property: 'og:url', content: canonicalUrl},
    {name: 'twitter:card', content: 'summary_large_image'},
    {name: 'twitter:title', content: product.title},
    {name: 'twitter:image', content: product.featuredImage?.url},
  ];
};

The meta function runs on the server. The returned descriptors serialize into the HTML head before the response is sent.

5.2 The Root Meta and Per Route Meta

The root route (app/root.tsx) sets defaults applying across the entire storefront: site name, default OG image, default Twitter handle, viewport, favicon, theme color.

// app/root.tsx
export const meta: MetaFunction = () => [
  {charSet: 'utf-8'},
  {name: 'viewport', content: 'width=device-width, initial-scale=1'},
  {property: 'og:site_name', content: 'Acme'},
  {property: 'og:image', content: 'https://example.com/og-default.jpg'},
  {name: 'twitter:site', content: '@acme'},
];

Per route meta merges with root meta. Per route descriptors override root for the same key.

5.3 Canonical URL Handling

Canonical URLs must be explicit per route. There is no automatic generation; merchant code constructs the canonical from loader data and route parameters. A helper takes the current request and constructs the canonical from the route's primary identifier without query strings, fragment, or trailing slash.

// app/lib/canonical.ts
export function getCanonical(path: string, locale?: string): string {
  const base = process.env.PUBLIC_SITE_URL || 'https://example.com';
  const localePrefix = locale && locale !== 'en' ? `/${locale}` : '';
  const cleanPath = path.replace(/\?.*$/, '').replace(/\/$/, '') || '/';
  return `${base}${localePrefix}${cleanPath}`;
}

Every route's meta function calls this helper. The pattern enforces consistency and avoids the most common Hydrogen failure mode: canonicals pointing to local paths, query strings included accidentally, or canonicals missing entirely.

5.4 The og:image Generation Pattern

Pattern A, Shopify CDN. Use the product's featured image directly. The Shopify CDN serves WebP and AVIF automatically and supports query string transformations. Recommended OG size: 1200 by 630 pixels.

const ogImage = product.featuredImage?.url
  ? `${product.featuredImage.url}&width=1200&height=630&crop=center`
  : 'https://example.com/og-default.jpg';

Pattern B, Dynamic OG image generation. Use an OG generator (Vercel's @vercel/og, a custom Lambda, or a self hosted Satori plus Resvg process) to render branded images with overlaid text. Pays off for content heavy stores where social share presentation is part of the marketing strategy.

5.5 The Hydrogen SEO Helper

Hydrogen ships an optional getSeoMeta helper in @shopify/hydrogen that produces meta descriptors from a structured SEO object. The helper handles the common cases (title, description, canonical, OG, Twitter) and is the recommended starting point.

import {getSeoMeta} from '@shopify/hydrogen';

export const meta: MetaFunction<typeof loader> = ({data}) => getSeoMeta(data?.seo);

export async function loader({params, context}: LoaderFunctionArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {variables: {handle: params.handle}});
  const seo = {
    title: product.title,
    description: product.description?.slice(0, 155),
    titleTemplate: '%s | Acme',
    media: product.featuredImage?.url,
    url: `https://example.com/products/${product.handle}`,
    jsonLd: {
      '@context': 'https://schema.org',
      '@type': 'Product',
      name: product.title,
      image: product.featuredImage?.url,
      description: product.description,
      offers: {
        '@type': 'Offer',
        priceCurrency: product.priceRange?.minVariantPrice?.currencyCode,
        price: product.priceRange?.minVariantPrice?.amount,
        availability: product.availableForSale ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock',
      },
    },
  };
  return json({product, seo});
}

The helper centralizes SEO conventions and produces both meta tags and JSON-LD. Use it where possible.

6. Schema Implementation in Hydrogen

Schema.org structured data in Hydrogen is fully manual. There is no equivalent to OS 2.0's automatic Product, BreadcrumbList, and Organization schema. Every schema entity is rendered by merchant code.

6.1 The JSON-LD Component Pattern

A small component that serializes a JavaScript object to a JSON-LD script tag:

// app/components/JsonLd.tsx
export function JsonLd({data}: {data: object}) {
  return (
    <script type="application/ld+json"
      dangerouslySetInnerHTML={{__html: JSON.stringify(data)}} />
  );
}

The dangerouslySetInnerHTML pattern is the standard React idiom for inline JSON-LD; the data is escaped as JSON which is safe in script context.

6.2 Product Schema

function ProductSchema({product}: {product: Product}) {
  const variant = product.selectedVariant || product.variants.nodes[0];
  const data = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    '@id': `https://example.com/products/${product.handle}#product`,
    name: product.title,
    description: product.description,
    image: product.images.nodes.map((img) => img.url),
    sku: variant?.sku,
    mpn: variant?.barcode,
    brand: {'@type': 'Brand', name: product.vendor || 'Acme'},
    offers: {
      '@type': 'Offer',
      '@id': `https://example.com/products/${product.handle}#offer`,
      priceCurrency: variant?.price.currencyCode,
      price: variant?.price.amount,
      availability: variant?.availableForSale ? 'https://schema.org/InStock' : 'https://schema.org/OutOfStock',
      url: `https://example.com/products/${product.handle}`,
      itemCondition: 'https://schema.org/NewCondition',
      seller: {'@type': 'Organization', '@id': 'https://example.com/#organization'},
      shippingDetails: {
        '@type': 'OfferShippingDetails',
        shippingRate: {'@type': 'MonetaryAmount', value: '0', currency: 'USD'},
        shippingDestination: {'@type': 'DefinedRegion', addressCountry: 'US'},
      },
      hasMerchantReturnPolicy: {
        '@type': 'MerchantReturnPolicy',
        applicableCountry: 'US',
        returnPolicyCategory: 'https://schema.org/MerchantReturnFiniteReturnWindow',
        merchantReturnDays: 30,
        returnMethod: 'https://schema.org/ReturnByMail',
      },
    },
  };
  return <JsonLd data={data} />;
}

Fields OS 2.0 themes do not auto populate (gtin, mpn, shippingDetails, hasMerchantReturnPolicy, hasVariant) are available in Hydrogen because merchant code constructs the schema explicitly from Storefront API data.

6.3 Organization Schema (Sitewide)

Render in the root layout so it appears on every route:

const organizationSchema = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  '@id': 'https://example.com/#organization',
  name: 'Acme',
  url: 'https://example.com',
  logo: {'@type': 'ImageObject', url: 'https://example.com/logo.png', width: 600, height: 60},
  sameAs: ['https://www.facebook.com/acme', 'https://www.instagram.com/acme', 'https://twitter.com/acme'],
  contactPoint: {
    '@type': 'ContactPoint',
    contactType: 'customer service',
    email: 'hello@example.com',
    availableLanguage: ['English'],
  },
};

The organization should appear once per page. Cross reference: framework-knowledgegraph.md.

6.4 BreadcrumbList Per Page

function BreadcrumbSchema({items}: {items: {name: string; url: string}[]}) {
  const data = {
    '@context': 'https://schema.org',
    '@type': 'BreadcrumbList',
    itemListElement: items.map((item, index) => ({
      '@type': 'ListItem', position: index + 1, name: item.name, item: item.url,
    })),
  };
  return <JsonLd data={data} />;
}

const breadcrumbs = [
  {name: 'Home', url: 'https://example.com/'},
  {name: 'Wallets', url: 'https://example.com/collections/wallets'},
  {name: product.title, url: `https://example.com/products/${product.handle}`},
];

Hydrogen does not automatically know which collection the user navigated through, so the pattern uses the product's primary collection or a metafield specifying the canonical breadcrumb path.

6.5 The @id Graph Pattern

Cross referencing schema entities via @id URIs lets search engines connect the product to its organization, breadcrumb, and offers as a coherent graph rather than disconnected blobs.

const productGraph = {
  '@context': 'https://schema.org',
  '@graph': [
    {'@type': 'Organization', '@id': 'https://example.com/#organization', name: 'Acme'},
    {
      '@type': 'WebSite',
      '@id': 'https://example.com/#website',
      url: 'https://example.com',
      publisher: {'@id': 'https://example.com/#organization'},
    },
    {
      '@type': 'BreadcrumbList',
      '@id': `https://example.com/products/${product.handle}#breadcrumb`,
      itemListElement: breadcrumbs.map((item, i) => ({
        '@type': 'ListItem', position: i + 1, name: item.name, item: item.url,
      })),
    },
    {
      '@type': 'Product',
      '@id': `https://example.com/products/${product.handle}#product`,
      name: product.title,
      brand: {'@id': 'https://example.com/#organization'},
      offers: {'@id': `https://example.com/products/${product.handle}#offer`},
    },
    {
      '@type': 'Offer',
      '@id': `https://example.com/products/${product.handle}#offer`,
      seller: {'@id': 'https://example.com/#organization'},
      itemOffered: {'@id': `https://example.com/products/${product.handle}#product`},
    },
  ],
};

The graph pattern is the 2026 preferred approach for sites with rich entity relationships. Cross reference: framework-schema.md.

6.6 Schema Generator Helpers

A common utility module produces schema for the most frequent entity types:

// app/lib/schema.ts
export function productSchema(product: Product, baseUrl: string) { /* ... */ }
export function collectionSchema(collection: Collection, baseUrl: string) { /* ... */ }
export function articleSchema(article: Article, baseUrl: string) { /* ... */ }
export function breadcrumbSchema(items: BreadcrumbItem[]) { /* ... */ }
export function organizationSchema() { /* ... */ }

Centralizing in app/lib/schema.ts prevents schema drift across routes; updates propagate automatically.

7. Performance Profile

Hydrogen on Oxygen achieves Lighthouse mobile performance 90 or higher when configured correctly per Shopify's Q3 2025 commerce platform case study covering 280 Hydrogen storefronts. Headline drivers: edge rendering, aggressive image optimization via the Shopify CDN, and Remix's deferred data pattern.

7.1 The Oxygen Edge Runtime Advantage

Oxygen runs Hydrogen storefronts on Shopify's global edge. TTFB advantage over Online Store themes is consistent: 100 to 300 ms at p50 mobile per Shopify's internal performance benchmarks across 2025. The advantage is largest for international users far from the merchant's home region.

For self hosted Hydrogen, the edge advantage is replaced by host proximity. A Hydrogen storefront on a single region Node.js host has identical TTFB to any other Node.js application from that region.

7.2 Bundle Size Discipline

Hydrogen 2 ships React, Remix runtime, and merchant route code to the client for hydration. Reasonable bundle sizes for a Hydrogen storefront in 2026: initial JavaScript payload (gzipped) under 80 KB for root layout plus first route, per route JavaScript (gzipped) under 40 KB additional for a typical product page, total JavaScript on first page load (gzipped) under 150 KB.

Bundles above 200 KB gzipped almost always indicate either an unbounded third party dependency or a missing code split boundary. Run rollup-plugin-visualizer quarterly; investigate any chunk above 50 KB.

7.3 Image Optimization via Shopify CDN

The Shopify CDN serves WebP and AVIF automatically based on Accept header. Hydrogen ships an Image component that handles srcset, sizes, loading, and format negotiation.

import {Image} from '@shopify/hydrogen';

<Image data={product.featuredImage} aspectRatio="1/1"
  sizes="(min-width: 768px) 50vw, 100vw" loading="eager" />

The component generates a <picture> element with multiple <source> tags for different formats and viewport sizes. For self hosted Hydrogen, the Shopify CDN still serves product images.

7.4 Caching Strategy

Hydrogen ships a cache abstraction (createWithCache) for Storefront API queries. Default policy is CacheLong (1 hour stale, 1 day stale-while-revalidate) suitable for most catalog data. Frequently changing data uses CacheShort or CacheNone.

import {CacheLong, CacheShort} from '@shopify/hydrogen';

const {product} = await context.storefront.query(PRODUCT_QUERY, {
  variables: {handle: params.handle}, cache: CacheLong(),
});
const {inventory} = await context.storefront.query(INVENTORY_QUERY, {
  variables: {handle: params.handle}, cache: CacheShort(),
});

Cache keys auto derive from the query and variables. On Oxygen the backend is Shopify's edge cache. On self hosted, common choices are an in memory LRU cache for single instance and Redis for multi instance.

7.5 Self Hosted Performance Profile

Self hosted Hydrogen on a Debian box behind nginx achieves the following baseline on a moderately specced VPS (4 vCPU, 8 GB RAM, gigabit network): TTFB at p50 80 to 150 ms from a co-located test client, LCP at p75 mobile (4G) 1.8 to 2.6 seconds, INP at p75 mobile under 200 ms, CLS at p75 under 0.1, Lighthouse mobile performance 88 to 95.

The numbers degrade with distance from the server's region; a US East Coast server serving European users adds 100 to 200 ms TTFB.

7.6 Core Web Vitals Tuning

Hydrogen specific notes on Core Web Vitals (full rubric: framework-pageexperience.md):

• LCP element on product pages is almost always the hero image. Preload via <link rel="preload"> in the meta function, set fetchpriority="high" on the image tag, ensure the image URL is in initial HTML.
• INP regresses when the route loader returns a large payload that React must reconcile on hydration. Slim loader responses to the fields the route renders.
• CLS regresses when the Shopify CDN serves an image with unspecified dimensions and the layout reflows. Always provide explicit width and height or aspectRatio via the Image component.

8. URL Structure and Routing

Hydrogen routing is entirely custom. The forced Shopify URL prefixes do not apply because Hydrogen renders its own URLs.

8.1 Remix File Based Routing

Routes are files in app/routes/. Filename conventions:

• app/routes/_index.tsx is the homepage at /.
• app/routes/products.$handle.tsx is /products/[handle].
• app/routes/collections.$handle.tsx is /collections/[handle].
• app/routes/$.tsx is a catch all route for 404 handling.
• Nested via dot notation: app/routes/account.orders.$id.tsx is /account/orders/[id].

The pattern gives total URL flexibility. A merchant can choose /products/[handle] (matching Shopify default), /shop/[handle] (cleaner), or any other scheme.

8.2 URL Mapping from Native Shopify

The most common Hydrogen build replaces an existing native Shopify storefront. Existing URLs are at /products/[handle], /collections/[handle], /pages/[handle], /blogs/[blog]/[article].

Pattern A, preserve Shopify URLs. Hydrogen routes mirror the Shopify scheme. No migration of inbound links; ranking signals carry over unchanged. This is the default and recommended pattern.

Pattern B, redesign URL scheme. Every old URL needs a 301 redirect to the new URL. URL mapping discipline becomes critical; cross reference framework-migration.md.

Pattern A is safer. The cleanup in Pattern B rarely justifies the ranking risk unless the existing URLs are demonstrably broken (numeric suffixes, generic handles, manufacturer auto generated handles).

8.3 Trailing Slash Policy

Remix does not enforce a trailing slash convention. Recommended in 2026: no trailing slash. Canonical URLs end without slash. Inbound requests with trailing slash 301 redirect to the bare URL.

// server.ts
export default {
  async fetch(request: Request, env: Env, executionContext: ExecutionContext) {
    const url = new URL(request.url);
    if (url.pathname.length > 1 && url.pathname.endsWith('/')) {
      url.pathname = url.pathname.replace(/\/$/, '');
      return Response.redirect(url.toString(), 301);
    }
    // ... rest of handler
  },
};

Canonical URLs in meta and JSON-LD must match the policy. Mixing trailing and non trailing across routes is the most common Hydrogen canonical bug.

8.4 Query Strings and Filtering

Collection filtering produces URL variations with query strings: /collections/wallets?filter.color=brown&sort=price-asc&page=2. The canonical points to the bare collection URL without query strings.

export const meta: MetaFunction<typeof loader> = ({data}) => {
  const canonical = `https://example.com/collections/${data.collection.handle}`;
  return [{tagName: 'link', rel: 'canonical', href: canonical}];
};

For high value filter combinations that should rank, use a structured sub URL pattern (/collections/wallets/brown) rendered as a separate route with its own canonical. Same Tier 1 vs Tier 2 vs Tier 3 facet policy documented in framework-shopify.md Section 4.5, ported to Hydrogen routing.

8.5 The i18n Routing Boundary

For multi country storefronts, the decision is between subpath routing (/en-us/products/widget) and subdomain routing (us.example.com/products/widget). Subpath is the default Hydrogen pattern via app/routes/($locale).products.$handle.tsx; the ($locale) prefix is optional and matches both /products/widget and /fr-fr/products/widget.

Subdomain requires separate Hydrogen deployments per locale or a single deployment with hostname based routing. Higher operational complexity; chosen when SEO requires per locale ranking isolation. Cross reference: Section 9 and framework-international.md.

9. International Hydrogen

Hydrogen's headless model gives full control over internationalization. The Storefront API supports @inContext directives for queries returning locale and country specific data. Hydrogen ships helpers wiring @inContext to the route's locale.

9.1 The i18n Strategy

Strategy A, locale subpath. /en-us/, /en-gb/, /fr-fr/, /de-de/. Single Hydrogen deployment, single domain, all locales under one storefront. Most common pattern in 2026.

Strategy B, locale subdomain. us.example.com, uk.example.com. Either separate deployments or one deployment with hostname routing. Used when per market ranking isolation is required.

Strategy C, ccTLD. example.com, example.co.uk, example.fr. Separate deployments per ccTLD. Highest operational complexity.

Cross reference: framework-international.md and framework-hreflang.md.

9.2 Subpath Routing Implementation

// app/routes/($locale).tsx
import {Outlet} from '@remix-run/react';
import {json, type LoaderFunctionArgs} from '@shopify/remix-oxygen';

export async function loader({params, context}: LoaderFunctionArgs) {
  const {locale} = params;
  const validLocales = ['en-us', 'en-gb', 'fr-fr', 'de-de'];
  if (locale && !validLocales.includes(locale)) {
    throw new Response('Not Found', {status: 404});
  }
  const [language, country] = (locale || 'en-us').split('-');
  context.storefront.i18n = {language: language.toUpperCase(), country: country.toUpperCase()};
  return json({locale: locale || 'en-us'});
}

export default function LocaleLayout() { return <Outlet />; }

The context.storefront.i18n setting flows through to subsequent Storefront API queries, automatically including @inContext(language: ..., country: ...). The catalog returns localized titles, descriptions, prices, and availability.

9.3 Automatic hreflang Generation

// app/lib/hreflang.ts
export function getHreflang(path: string, currentLocale: string) {
  const locales = ['en-us', 'en-gb', 'fr-fr', 'de-de'];
  const baseUrl = 'https://example.com';
  const cleanPath = path.replace(/^\/[a-z]{2}-[a-z]{2}/, '');
  const tags = locales.map((locale) => ({
    tagName: 'link', rel: 'alternate', hrefLang: locale,
    href: `${baseUrl}/${locale}${cleanPath}`,
  }));
  tags.push({tagName: 'link', rel: 'alternate', hrefLang: 'x-default', href: `${baseUrl}/en-us${cleanPath}`});
  return tags;
}

Called from every route's meta function:

export const meta: MetaFunction<typeof loader> = ({location, params}) => {
  return [...getHreflang(location.pathname, params.locale || 'en-us')];
};

The pattern enforces hreflang consistency. Missing locales, broken self references, and asymmetric clusters are the most common hreflang bugs; centralizing the cluster generation prevents them.

9.4 Per Locale Product Catalog

The Storefront API returns localized product data when @inContext is set. Localized fields: title, description, options, translatable metafields, SEO title and SEO description, and price in local currency. Fallback behavior: untranslated fields return the primary locale's value. Translation gaps appear in Search Console as duplicate content warnings; the cleanest fix is to noindex untranslated routes or provide proper translations.

9.5 Currency Handling

Currency follows country context. The Storefront API returns prices in the country's currency when the country code is set in @inContext. Merchant code uses the returned currencyCode field for display.

function formatPrice(amount: string, currencyCode: string, locale: string) {
  return new Intl.NumberFormat(locale, {style: 'currency', currency: currencyCode}).format(parseFloat(amount));
}

Currency conversion handled by Shopify's Markets configuration. The merchant configures FX rates per market; the Storefront API applies them automatically. Custom FX logic in storefront code is rarely needed and is a code smell.

10. Customer Account API and SEO

The Customer Account API is Shopify's modernized customer authentication and account management surface, GA since 2023, with Hydrogen integration helpers since 2024.

10.1 The Customer Account API in Hydrogen

The API handles login, registration, order history, address management, and subscription management. Authentication is OAuth 2.0 with Shopify as identity provider; tokens stored in HTTP only cookies. Account routes live at /account, /account/login, /account/orders, /account/addresses. These are not indexable.

// app/lib/customer-account.ts
import {createCustomerAccountClient} from '@shopify/hydrogen';

export function getCustomerAccountClient(env: Env, request: Request) {
  return createCustomerAccountClient({
    waitUntil: env.waitUntil,
    request,
    session: env.session,
    customerAccountId: env.PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID,
    customerAccountUrl: env.PUBLIC_CUSTOMER_ACCOUNT_API_URL,
  });
}

10.2 The Gated Content Pattern

Some merchants ship gated content: members only catalog, B2B price lists, exclusive collections for VIP customers. The clean pattern: the SSR shell renders a marketing description and a login prompt for unauthenticated requests. Crawlers see the marketing shell and index the route on its marketing content. The personalized layer hydrates after authentication.

export async function loader({context, request}: LoaderFunctionArgs) {
  const customer = await context.customerAccount.getCustomer();
  if (!customer) {
    return json({authenticated: false, marketingContent: MARKETING_PITCH});
  }
  const exclusiveProducts = await context.storefront.query(EXCLUSIVE_QUERY);
  return json({authenticated: true, customer, exclusiveProducts});
}

The crawler sees the unauthenticated branch. The authenticated customer sees the exclusive catalog. The route is indexable on its marketing surface.

10.3 The Static Marketing Plus Dynamic Account Boundary

Hydrogen storefronts cleanly separate two layers:

• Indexable layer: home, collections, products, articles, search, pages, marketing. SSR with caching, full schema, full meta, hreflang, sitemaps.
• Personalized layer: cart, account, checkout, order history, subscriptions. SSR with no caching, noindex robots meta, no schema, no hreflang.

The boundary is enforced via a robots middleware setting X-Robots-Tag: noindex, nofollow on personalized routes:

// app/lib/robots-headers.ts
export function getRobotsHeader(pathname: string): string | undefined {
  const noindexPaths = ['/account', '/cart', '/checkout', '/api'];
  if (noindexPaths.some((p) => pathname.startsWith(p))) return 'noindex, nofollow';
  return undefined;
}

The noindex applies even if a crawler follows an authenticated link; the personalized surface is invisible to indexes.

10.4 The Account Login Redirect Anti Pattern

A common failure mode: the entire storefront redirects unauthenticated requests to /account/login, including the homepage and product pages. This produces 302 redirects to noindexed login routes; the indexable storefront ranks for nothing. The fix: authentication is required only for personalized routes. Marketing routes serve to anyone.

11. Migration from Native Shopify

The most common Hydrogen project is a replacement for an existing native Shopify Online Store theme.

11.1 The Decision Criteria

Before greenlighting, validate the merchant meets criteria from Section 1.1. The migration should not happen because Hydrogen is the new shiny option; it should happen because the existing theme is blocking specific business outcomes.

Cost of moving from a Dawn theme to Hydrogen ranges 50K to 250K USD initial plus 30K to 150K USD annual maintenance.

11.2 The URL Mapping Discipline

The single most important migration variable. Hydrogen retains Shopify URL conventions by default. Preserving the URL scheme means no URL mapping required; ranking signals carry over unchanged.

If the merchant redesigns URLs during migration, every old URL needs a 301 redirect. The migration becomes a URL mapping project, not just a theme rebuild. Recommended default: preserve URLs.

11.3 The Migration Sequence

1. Catalog audit. Export the full catalog. Document the URL inventory.
2. Hydrogen scaffold. Initialize the project, configure Storefront API tokens, set up deployment.
3. Route parity build. Replicate every existing template type. Product, collection, article, page, search, cart at minimum.
4. Schema parity validation. Confirm Product, Collection, Organization, BreadcrumbList schema on every applicable route.
5. Meta parity validation. Crawl staging; diff titles, descriptions, canonicals, Open Graph against production theme.
6. Performance validation. Lighthouse mobile must equal or exceed the existing theme.
7. Hreflang validation (multi market). Confirm clusters render on every locale and every route.
8. Sitemap generation. Generate sitemap.xml from the Storefront API. Submit to Search Console at launch.
9. Robots and crawl access. Confirm robots.txt allows indexable routes and blocks /account, /cart, /checkout, /api.
10. Cutover. DNS swap from theme to Hydrogen. Submit the new sitemap. Monitor 404 rates, Search Console coverage, and ranking changes for 30 days.

Cross reference: framework-migration.md.

11.4 The Gradual Migration Pattern

For large merchants, a big bang cutover carries high risk. The gradual pattern: Hydrogen serves a subset of routes via a reverse proxy fronting both theme and Hydrogen, gradually expanding Hydrogen coverage.

location ~ ^/collections/(featured-collection|new-arrivals) {
  proxy_pass http://hydrogen-backend;
}
location ~ ^/products/ {
  proxy_pass http://shopify-theme;
}
location / {
  proxy_pass http://shopify-theme;
}

The pattern reduces blast radius and allows per route rollback. The tradeoff is increased operational complexity.

11.5 Migration Audit Rubric

Score 14. Acceptable: 12 or higher. Below 12, the migration introduces ranking risk that should be remediated.

12. Hydrogen Deployment

12.1 Oxygen Default

Oxygen is Shopify's edge runtime for Hydrogen. Free with all Shopify plans since 2023.

npm create @shopify/hydrogen@latest -- --template hello-world
cd my-storefront
npm install
npm run dev
npm run deploy

Oxygen handles SSL, edge routing, environment variables, preview deployments per branch, and integration with the Shopify CDN. Operational characteristics: edge runtime on Shopify's global infrastructure, TTFB under 200 ms globally, no infrastructure management, deployment in approximately 60 seconds per push. Cost included with the Shopify plan.

12.2 Vercel and Netlify

Hydrogen on Vercel uses Vercel's Remix adapter. Edge runtime gives comparable TTFB to Oxygen. Advantage: access to Vercel's broader feature set for merchants already invested. Disadvantage: cost scales with bandwidth and function executions. Hydrogen on Netlify uses Netlify's Remix adapter; similar economics to Vercel.

12.3 AWS Lambda Plus CloudFront

Hydrogen on AWS uses an AWS Lambda function for SSR with CloudFront in front. Higher operational burden, more control. Chosen by enterprise merchants with existing AWS investment.

12.4 Self Hosted Node.js

Hydrogen as a long running Node.js process behind nginx. The pattern Joseph's infrastructure uses; documented in Section 14. Suited for: merchants who want sovereignty, EU data residency requirements satisfied by EU based hosting, integration with existing self hosted infrastructure, or the desire to avoid platform fees beyond Shopify itself. Not suited for: merchants without operational discipline or merchants whose traffic patterns require global edge presence that a single region cannot provide.

12.5 The Deployment Pipeline

Regardless of target, the pipeline shape is similar:

npm ci
npm run lint
npm run typecheck
npm run test
npm run build
# Deploy step varies by target

Preview deployments per branch are operationally critical. Every pull request should produce a deployed preview URL. Oxygen, Vercel, and Netlify support this natively. Self hosted requires a deployment script that provisions a preview URL on the same or staging host.

13. Hydrogen vs Other Headless Patterns

13.1 Hydrogen vs Next.js Commerce

Next.js Commerce is Vercel's React based commerce template, supporting Shopify, BigCommerce, Saleor, and Vendure backends. Built on Next.js App Router with React Server Components.

Recommendation: Hydrogen for stores committed to Shopify. Next.js Commerce for stores wanting backend portability or already invested in Next.js.

13.2 Hydrogen vs Catalyst for BigCommerce

Catalyst is BigCommerce's equivalent: a React based framework for headless storefronts, built on Next.js, with first class BigCommerce integration. The choice is the choice between Shopify and BigCommerce as the commerce platform, not the framework. Cross reference: framework-shopify.md and framework-ecommerceseo.md.

13.3 Hydrogen vs Storefront UI Generic

Storefront UI is a Vue based open source storefront framework, platform agnostic. For React teams: Hydrogen or Next.js Commerce. For Vue teams: Storefront UI or Nuxt Commerce. The framework choice follows team expertise.

13.4 The Platform Tied vs Platform Agnostic Tradeoff

Platform tied (Hydrogen, Catalyst): tightest integration with the underlying commerce platform. Helpers ship out of the box. Lock in is real; switching commerce platforms requires a framework migration.

Platform agnostic (Next.js Commerce, Storefront UI): backend portability via adapter pattern. Lower lock in. Larger community. But every adapter is slightly behind first class integrations.

If the merchant is definitively staying on Shopify, Hydrogen is the cleaner choice. If hedging on platform commitment, the agnostic option pays integration overhead for the option value of switching later.

14. Bubbles Hosted Hydrogen

Joseph's infrastructure runs a self hosted Hydrogen pattern on Bubbles (Debian amd64, nginx, IP 169.155.162.118) for a small portfolio of Shopify stores that have justified the headless investment.

14.1 The Architecture

The Hydrogen storefront runs as a Node.js 20 process managed by PM2. Nginx fronts the Node.js process with HTTP/3 termination, SSL via Let's Encrypt, and static asset caching. The Shopify Storefront API serves catalog data; the Shopify CDN serves product images.

Browser → HTTPS (HTTP/3) → nginx (Bubbles, 443)
   → http://127.0.0.1:3000 (Hydrogen Node.js process via PM2)
   → Shopify Storefront API (https://[store].myshopify.com/api/2025-04/graphql.json)
   → Shopify CDN (https://cdn.shopify.com/...)

No third party CDN or proxy in front of nginx. Bubbles handles SSL termination, serves Hydrogen HTML, and proxies static assets directly.

14.2 The Server Layout

/var/www/sites/example.com/
  app/                              # Hydrogen source
  public/                           # static assets
  dist/                             # build output
  package.json
  vite.config.ts
  ecosystem.config.js               # PM2 config
  .env                              # Storefront API tokens, never committed

14.3 The PM2 Process Manager

PM2 manages the long running Node.js process. Restart on crash, log rotation, multi instance via cluster mode.

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'hydrogen-example-com',
    script: './dist/server/index.js',
    instances: 2,
    exec_mode: 'cluster',
    env: {NODE_ENV: 'production', PORT: 3000},
    env_file: '.env',
    error_file: '/var/log/hydrogen/example-com-error.log',
    out_file: '/var/log/hydrogen/example-com-out.log',
    max_memory_restart: '1G',
  }],
};

Two instances in cluster mode share the port via Node's cluster module. PM2 systemd integration via pm2 startup systemd -u user --hp /home/user then pm2 save persists the process list across reboots.

14.4 The nginx Reverse Proxy

server {
  listen 443 ssl http2;
  listen 443 quic reuseport;
  server_name example.com;

  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
  ssl_protocols TLSv1.2 TLSv1.3;
  add_header Alt-Svc 'h3=":443"; ma=86400' always;

  root /var/www/sites/example.com/public;

  location /assets/ {
    alias /var/www/sites/example.com/dist/client/assets/;
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
  }

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 60s;
  }

  add_header X-Content-Type-Options "nosniff" always;
  add_header X-Frame-Options "SAMEORIGIN" always;
  add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

  gzip on;
  gzip_types text/plain text/css application/json application/javascript text/xml;
  brotli on;
  brotli_types text/plain text/css application/json application/javascript;
}

server {
  listen 80;
  server_name example.com www.example.com;
  return 301 https://example.com$request_uri;
}

The pattern preserves the network canonical (non www) discipline per the 2026 Joseph network standardization.

14.5 The Deployment Pipeline

#!/bin/bash
# /usr/local/bin/deploy-hydrogen-example-com.sh
set -e
cd /var/www/sites/example.com
git fetch origin
git checkout main
git pull origin main
npm ci
npm run build
pm2 reload ecosystem.config.js --update-env
echo "Deployment complete at $(date)"

Triggered manually via SSH or via a webhook from GitHub Actions on push to main. The webhook approach uses a small Node.js endpoint on Bubbles that verifies the GitHub signature and runs the deploy script.

For staging, a parallel deployment lives at /var/www/sites/staging.example.com/ on port 3001 with a separate PM2 process and a separate nginx vhost.

14.6 Environment Variables

Storefront API tokens, customer account credentials, and other secrets live in .env files outside the git repository. PM2 loads them via env_file.

# /var/www/sites/example.com/.env (never committed)
PUBLIC_STOREFRONT_API_TOKEN=...
PRIVATE_STOREFRONT_API_TOKEN=...
PUBLIC_STORE_DOMAIN=example.myshopify.com
PUBLIC_STOREFRONT_API_VERSION=2025-04
PUBLIC_STOREFRONT_ID=...
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=...
PUBLIC_SITE_URL=https://example.com
SESSION_SECRET=...

Permissions on .env set to 600. Rotation policy: every 12 months at minimum, immediately if a leak is suspected.

14.7 Logs and Monitoring

PM2 produces stdout and stderr logs at /var/log/hydrogen/ with rotation via pm2-logrotate (size based, 14 day retention). Nginx access logs at /var/log/nginx/example.com.access.log; errors at /var/log/nginx/example.com.error.log. Standard logrotate applies.

A cron job on Bubbles checks Hydrogen process health every five minutes by hitting http://127.0.0.1:3000/health and alerts via webhook if the response is not 200.

// app/routes/health.tsx
export async function loader() {
  return new Response('ok', {status: 200});
}

14.8 The Staging Production Split

Staging deployments mirror production at staging.example.com. Same Hydrogen code, same Shopify store (or a development store), same nginx vhost configuration on a different subdomain.

Staging is robotted out via robots.txt (User-agent: * then Disallow: /). Belt and suspenders: nginx returns X-Robots-Tag: noindex, nofollow on every response from staging via add_header X-Robots-Tag "noindex, nofollow" always;.

14.9 No Third Party CDN or Proxy

The pattern explicitly does not place a third party CDN, proxy, or edge service in front of nginx. SSL terminates at Bubbles. Static assets serve from Bubbles. Hydrogen renders at Bubbles. Only the Shopify Storefront API and Shopify CDN are external.

Reasoning: sovereignty over the request path, predictable performance, simpler debugging, no vendor dependency beyond Shopify for the catalog. The tradeoff is single region performance; for the small portfolio Joseph operates, this is acceptable. For a global ecommerce brand it would not be.

14.10 The Operational Discipline Required

Self hosted Hydrogen is not a beginner pattern. Required discipline: server patching and security updates, SSL renewal via Let's Encrypt and certbot, Node.js version management (Node 20 LTS in 2026; upgrade plan to Node 22 LTS during maintenance windows), Storefront API version migration every 12 months, log retention and disk space management, backup of code (git remote) and .env files (encrypted offline copy), monitoring and alerting for process health.

Without this discipline, the pattern degrades and the merchant ends up with worse uptime than Oxygen would provide for free. For everyone else, Oxygen is the correct choice.

End of Framework

This framework documents Shopify Hydrogen as an SEO surface across the dimensions that matter in 2026: the Remix on Vite architecture, Storefront API integration, deployment options spanning Oxygen and self hosted Node.js, the SSR rendering model, manual schema implementation discipline, international routing, the Customer Account API boundary, migration from native themes, and the operational pattern for self hosted Hydrogen on Debian behind nginx.

Hydrogen in 2026 is the mature option for merchants who have outgrown Online Store themes and have the engineering capacity to maintain a custom React storefront. The SEO posture is excellent when the framework's defaults are respected (SSR with full meta and schema, canonical discipline per route, hreflang generation from a centralized helper, performance budget enforcement). It degrades quickly when the team treats Hydrogen as a CSR React app and lets the SSR layer atrophy.

The decision between Hydrogen and the native Online Store theme is rarely an SEO decision. It is an engineering capacity and brand differentiation decision. SEO is downstream; it gets handled correctly on either platform when implementation discipline is in place.

Companion frameworks:

• framework-shopify.md for the native Shopify theme and platform constraints.
• framework-ecommerceseo.md for cross platform e-commerce foundations.
• framework-cross-stack-implementation.md for per framework code equivalents.
• framework-schema.md for the comprehensive schema reference.
• framework-hreflang.md for the hreflang tag reference.
• framework-international.md for the strategic international SEO framework.
• framework-migration.md for the migration playbook.
• framework-pageexperience.md for Core Web Vitals.
• framework-headless.md for the headless CMS architecture context.
• framework-react.md for the React SPA SEO baseline.
• framework-mobileseo.md for mobile specific commerce optimization.
• framework-aicitations.md for AI citation patterns.
• framework-aioverviews.md for Google AI Overviews optimization.