Dev Stack
Shopify Hydrogen in South Africa: setup and hard-won gotchas.
South African brands scaling past R500k/month on a Liquid theme usually hit the same wall — Online Store 2.0 gives you flexibility but not performance, and Checkout Extensibility forces changes you do not want to ship. Hydrogen is Shopify's React + Remix framework running on Oxygen, Shopify's hosted edge (which is itself Cloudflare Workers under the hood). For a .co.za shop with a .co.uk or .com.au sister site, Hydrogen gives you one codebase, per-market currencies (ZAR, USD, GBP), and proper server-rendered performance. The caveats are real: Payfast is not a native Shopify Payments partner on Hydrogen headless checkout the way it is on Liquid, Oxygen egress bills in USD, and Hydrogen usually lags Remix major versions by 6–12 months. This guide walks the setup we use for SA merchants who have already outgrown Dawn.
Prerequisites
- A Shopify store on Basic plan or higher with API access
- Node 20+ and npm
- A Storefront API access token with unauthenticated_read_product_listings scope
- Decision made on currencies: ZAR primary, plus any export markets
- A domain strategy — apex .co.za, or .com with /za subpath
Step 1. Scaffold a Hydrogen project
Use the official create-hydrogen script. Pick the Remix version it suggests — do not upgrade Remix manually, Hydrogen pins specific versions for a reason.
npm create @shopify/hydrogen@latest
cd your-hydrogen-store
npm installStep 2. Wire the Storefront API token
Create a custom app in Shopify admin, enable Storefront API scopes, copy the Storefront API access token. Hydrogen reads it from .env — never commit this file.
SESSION_SECRET="generate-with-openssl-rand-hex-32"
PUBLIC_STORE_DOMAIN="your-store.myshopify.com"
PUBLIC_STOREFRONT_API_TOKEN="your-token-here"
PUBLIC_STOREFRONT_ID="123456"
PUBLIC_CHECKOUT_DOMAIN="checkout.yourstore.co.za"Step 3. Configure i18n for .co.za and export markets
Hydrogen i18n has three modes: Subdomain, Subpath, Top-level domain. For a single SA-primary brand, run the apex as ZA default and scope export markets to /uk or /us subpaths. Shopify Markets must be configured with matching country handles.
export type I18nLocale = {
language: 'EN';
country: 'ZA' | 'GB' | 'US';
pathPrefix: string;
currency: 'ZAR' | 'GBP' | 'USD';
};
export function getLocaleFromRequest(request: Request): I18nLocale {
const url = new URL(request.url);
const first = url.pathname.split('/')[1]?.toLowerCase();
if (first === 'uk') return { language: 'EN', country: 'GB', pathPrefix: '/uk', currency: 'GBP' };
if (first === 'us') return { language: 'EN', country: 'US', pathPrefix: '/us', currency: 'USD' };
return { language: 'EN', country: 'ZA', pathPrefix: '', currency: 'ZAR' };
}Step 4. Deploy to Oxygen
Oxygen is the Shopify-hosted edge runtime. Connect your repo via Shopify admin → Hydrogen → Deploy. Push to main triggers a production deploy; every PR gets a preview URL. Oxygen is free on paid Shopify plans with Hydrogen enabled — talk to your Shopify rep for SA pricing in USD.
npx shopify hydrogen link
npx shopify hydrogen deployStep 5. Alternative: self-host on Cloudflare Workers
If Oxygen cost or egress worry you, Hydrogen runs on any Workers-compatible runtime. Export a Worker handler and deploy with Wrangler. You lose the built-in Shopify analytics and one-click preview, but gain control and JNB/CPT PoP termination for free.
Step 6. Connect Shopify Markets for ZAR
In Shopify admin → Settings → Markets, create a South Africa market with ZAR as the local currency. Hydrogen reads market config via the Storefront API automatically. Prices show in ZAR for ZA visitors; export markets see their local currency. Pricing rules (e.g. +15% for GB) set here apply globally.
Step 7. Checkout: stay on Shopify-hosted
Hydrogen handoff sends the cart to Shopify's hosted checkout at checkout.yourstore.co.za. You do not build your own checkout — that is where Payfast, Yoco, Peach and Payflex integrations live. See our Payfast guide for the gateway install.
Step 8. Set the canonical host and SEO
In routes/_index.tsx add canonical link generation using the request URL and strip tracking params. Also generate sitemap.xml via Hydrogen's built-in route — Shopify Markets will produce per-country hreflang tags if Markets is configured correctly.
SA gotchas
- Payfast has no official Hydrogen integration. It works on Shopify-hosted checkout (which Hydrogen hands off to), so do not be tempted to build a custom checkout — you will lose Payfast access and violate the Payfast + Shopify terms.
- Hydrogen major versions lag Remix by 6–12 months. Do not npm update @remix-run/react manually — it will break Oxygen deploy. Wait for the Hydrogen upgrade release notes.
- Oxygen egress is billed in USD and not cheap for image-heavy ZA storefronts. Move product images to Shopify CDN (which is free) rather than serving them through Oxygen. Or self-host on Workers and use Cloudflare Images in the JNB PoP.
- B2B customer accounts API is still in beta at time of writing. If you sell wholesale to South African retailers, check the current API status before committing to Hydrogen for the B2B flow — Liquid + Shopify Plus B2B is often still the safer bet.
- Hydrogen's /.well-known/shopify/monorail analytics endpoint is blocked by aggressive ad blockers common on SA corporate networks. Do not rely solely on it — also run server-side pixels for paid traffic reporting.
- Oxygen does not have a South African region. Requests terminate at the nearest Shopify edge (usually Europe for SA traffic). This is still faster than unoptimised Liquid themes on Shopify Plus, but slower than self-hosted Workers pinned to JNB.
Frequently asked questions
Is Hydrogen worth it for a R1M/month South African store?
If you are pushing Dawn or Craft to its limit and seeing >3s LCP on 4G, Hydrogen pays back in conversion uplift within a quarter. Under R500k/month, stay on a well-tuned Liquid theme — the engineering cost of Hydrogen only earns out with traffic scale.
Can I use Hydrogen with Payfast and Yoco?
Yes — Hydrogen hands checkout to Shopify-hosted checkout, where Payfast, Yoco, Peach, Ozow and Payflex are all available as standard Shopify payment gateways. See our Payfast Shopify guide for the gateway setup.
Do I need Shopify Plus for Hydrogen?
No. Hydrogen works on any Shopify plan from Basic up. Oxygen hosting is free on paid plans with Hydrogen enabled. Plus gets you scripts, unlimited checkout extensibility and better rate limits — but Hydrogen itself is plan-agnostic.
What hosting region serves South African Hydrogen visitors?
Oxygen routes requests to the nearest Shopify edge — usually a European PoP for ZA traffic, adding ~170ms to Johannesburg and ~180ms to Cape Town. Self-hosting on Cloudflare Workers gives you JNB and CPT termination for sub-50ms TTFB.