The Decision That Changed Everything
When we started building Potatuhs, we had a choice that every new Shopify merchant faces: use a theme, or go headless. For most stores, the answer is obvious — pick a theme, customize it, and start selling. Themes are fast, reliable, and battle-tested. There's no shame in using one.
We went headless anyway. Here's why, and what we learned.
What "Headless" Actually Means
For the non-developers reading this (and we hope there are some — this isn't just a tech blog), "headless commerce" means separating the front end of your store (what customers see) from the back end (where products, orders, and inventory live).
In a traditional Shopify setup, the theme IS the front end. It's built with Shopify's Liquid templating language, hosted on Shopify's servers, and tightly coupled to Shopify's rendering pipeline. You customize it through the theme editor, and Shopify handles everything from routing to checkout.
In a headless setup, Shopify's back end still manages products, orders, payments, and all the commerce logic. But the front end is a completely separate application — in our case, a React app built with Shopify's Hydrogen framework, hosted on Shopify's Oxygen platform.
Think of it like this: a traditional Shopify store is a restaurant where the kitchen and the dining room are the same room. A headless store is a restaurant where the kitchen is in the back, the dining room is in the front, and they communicate through a window (the Storefront API). You get a much better dining room, but you have to build it yourself.
Why Hydrogen Specifically
Shopify released Hydrogen in 2022 as their official React-based framework for building custom storefronts. It's built on top of Remix (now part of React Router v7), which means it supports server-side rendering (SSR), streaming, and all the modern web performance techniques that make fast sites fast.
We chose Hydrogen over other headless options (Next.js, Gatsby, custom builds) for several reasons:
First-party Shopify integration. Hydrogen comes with built-in hooks and utilities for the Storefront API. Cart management, product queries, collection filtering — all of it is handled by purpose-built components and functions. You're not writing boilerplate GraphQL queries from scratch (though you can if you want to).
Oxygen hosting. Shopify's Oxygen platform hosts Hydrogen apps at the edge, meaning your store is served from the data center closest to each visitor. This is the same infrastructure Shopify uses for its own properties. The performance is excellent, and you don't have to manage servers, CDNs, or deployment pipelines. Push to your Git repo, and Oxygen deploys automatically.
Remix architecture. Remix's approach to data loading (loaders), form handling (actions), and nested routing is genuinely elegant. Each route can define exactly what data it needs, and that data is fetched on the server before the page renders. No loading spinners. No layout shift. The page arrives complete.
React ecosystem. Because Hydrogen is React, we have access to the entire React ecosystem — component libraries, state management tools, animation libraries, testing frameworks. This is a massive advantage over Liquid, which is a templating language with a much smaller ecosystem.
The Technical Stack
Here's what Potatuhs runs on:
- Framework: Shopify Hydrogen (Remix-based)
- Language: TypeScript + React
- Hosting: Shopify Oxygen (edge deployment)
- CDN: Cloudflare (additional caching layer)
- API: Shopify Storefront API (GraphQL)
- Analytics: Google Analytics 4
- Styling: CSS with custom properties
- Images: Shopify CDN with responsive srcset
The site is server-side rendered on every request, which means search engines see fully rendered HTML (great for SEO), and users see content immediately without waiting for JavaScript to hydrate. We use Cloudflare as an additional caching layer in front of Oxygen for static assets and edge caching.
What We Gained
Complete creative control. This is the big one. With a theme, you're working within the constraints of someone else's design system. With Hydrogen, every pixel is ours. The marquee grid of potato characters on our homepage? The custom product carousel? The animated transitions? None of that would be possible (or at least easy) with a standard theme.
Performance. Our site loads fast. Really fast. Server-side rendering means the initial page load is a complete HTML document, not a blank page waiting for JavaScript. Oxygen's edge hosting means that document is served from nearby. And React's hydration model means the page becomes interactive quickly after load.
Developer experience. Building in React with TypeScript is genuinely enjoyable. Hot module replacement means changes appear instantly in development. Type safety catches bugs before they reach production. Component-based architecture means we can build, test, and reuse UI elements efficiently.
Future flexibility. Because our front end is decoupled from Shopify, we could theoretically swap out the back end without rebuilding the customer experience. We're not planning to leave Shopify (it's excellent for what we need), but the optionality is valuable.
What We Lost (and What It Cost)
Let's be honest about the trade-offs, because every headless commerce blog post that only talks about the benefits is lying to you.
Development time. Building a custom Hydrogen storefront takes significantly longer than setting up a theme. We spent weeks on things that would have been instant with a theme — navigation, product pages, cart functionality, search, filtering. Every feature that a theme gives you for free, we had to build from scratch.
The Shopify theme editor. With a theme, non-developers can make changes through Shopify's visual editor. With Hydrogen, every change requires code. Want to update the homepage layout? That's a pull request. Want to add a promotional banner? Code. This is fine for a developer-run brand like us, but it would be a dealbreaker for a team without engineering resources.
App ecosystem compatibility. Many Shopify apps are designed to inject code into Liquid themes. They don't work with Hydrogen out of the box. Some apps offer API-based alternatives, but others simply aren't compatible. We had to build custom solutions for functionality that would have been a one-click app install on a theme.
Checkout. Even with Hydrogen, checkout still runs on Shopify's hosted checkout (unless you're on Shopify Plus). This means there's a visual transition when customers go from your custom storefront to Shopify's checkout page. We've customized the checkout as much as Shopify allows, but it's still not a seamless experience.
Lessons Learned
Start with the Hydrogen template. Shopify provides a starter template that includes basic commerce functionality — product pages, collections, cart, search. Don't try to build everything from scratch. Start with the template and customize from there.
Understand the Storefront API. Hydrogen abstracts a lot of the API complexity, but you still need to understand how GraphQL queries work, what data is available, and how pagination, filtering, and metafields function. Read the Storefront API docs thoroughly before you start building.
Cache aggressively. Hydrogen and Oxygen support multiple caching strategies. Use them. Server-side rendering is fast, but serving a cached response is faster. We cache product pages, collection pages, and blog content with short TTLs that balance freshness with performance.
Test on real devices. Development on a fast laptop with localhost is not representative of real-world performance. Test on phones, on slow connections, on devices that are three years old. That's where performance problems surface.
Don't go headless unless you need to. This is the most important lesson. If a theme would serve your needs, use a theme. Headless commerce is powerful, but it's also complex, time-consuming, and requires ongoing engineering investment. We chose it because we wanted complete creative control and because we have the technical skills to build and maintain it. If either of those things weren't true, we'd be happily running a theme.
Was It Worth It?
For us? Absolutely. Potatuhs looks and feels exactly the way we want it to. The brand personality comes through in every interaction, every animation, every page transition. That wouldn't have been possible with a theme — or at least, it would have required so many theme customizations that we'd have been fighting the theme instead of building with it.
But we're also a team with strong technical skills and a willingness to invest development time in the storefront. For a different team, with different skills and different priorities, the answer might be different.
If you're considering Shopify Hydrogen for your own project, feel free to reach out. We're happy to share more about our experience and help you decide if headless is right for you.
And if you just came here for the potato content and accidentally learned something about web development — you're welcome.
— The Potatuhs Team
