Sua Mesa Fit
Headless Shopify storefront on Hydrogen
In plain English
An online food store where the shop management stays in Shopify but the entire customer-facing site is custom-built, so it looks unique and loads fast.
My role
Frontend developer
Timeline
2 months
Team
Small team
Status
Live
Design
Product tour
Section 01
The problem
Shopify themes are quick to launch and hard to differentiate. The client needed the operational side of Shopify — inventory, orders, payments, fulfilment — but a storefront that did not look like every other store, with control over performance and layout that a theme cannot give you.
Section 02
How I approached it
Headless. Shopify keeps running the business logic and admin, while the storefront is a separate Hydrogen application that fetches data over GraphQL. That means total freedom in the UI layer with none of the risk of rebuilding checkout or payments.
Outcome
A fully custom storefront with server-rendered product pages, a fast search experience, and cart shipping calculation, backed by the Shopify infrastructure the client already ran their business on.
Section 03
Going deeper
What 'headless' means in practice
A traditional store couples the admin and the website: you install a theme and customise within its limits. Headless separates them. Shopify remains the source of truth for products, prices, inventory, and orders, exposed through APIs. The website becomes an independent application that reads from those APIs. You gain complete design and performance control, and you take on the responsibility of building the storefront yourself.
Why Hydrogen and Remix
Hydrogen is Shopify's own framework built on Remix. It ships with the Storefront API client, cart handling, and caching conventions already wired up. Remix's server-first data loading means product pages render on the server with real data, which matters for both perceived speed and SEO on a commerce site.
Two APIs, two purposes
The Storefront API serves the customer: products, collections, cart. The Admin API handles privileged operations that need server-side credentials. Keeping the boundary strict is a security requirement, not a stylistic choice — admin credentials never cross into the browser.
Section 04
The build process
Audit the catalogue
Product structure, variants, and collections came first. The data model dictates what the UI can express.
Build the component system
Product cards, variant selectors, cart line items, and search results as reusable pieces before assembling pages.
Optimise the search path
Search is where commerce conversions are won or lost. Query shape and result rendering were tuned specifically.
Wire cart and shipping
Cart state, line item updates, and shipping cost calculation integrated against the Storefront API with optimistic UI.
Section 05
How the pieces fit together
Each layer has one job. Read it top to bottom — that's roughly the path a request takes through the system.
Hydrogen / Remix
Server-rendered routes with nested data loaders and streaming.
Shopify Storefront API
GraphQL queries for products, collections, search, and cart mutations.
Shopify Admin API
Server-only operations that require elevated credentials.
Shopify checkout
Payments, taxes, and fulfilment stay on battle-tested Shopify infrastructure.
Section 06
What it does
Custom component library
Every storefront element built from scratch rather than inherited from a theme.
Optimised product search
Tuned GraphQL queries and result rendering for fast, relevant results.
Cart with shipping calculation
Live shipping cost feedback inside the cart before checkout.
Server-rendered pages
Product and collection pages render on the server for speed and SEO.
Section 07
The hard parts
GraphQL over-fetching
Naive queries pull far more than a page needs. Query shapes were trimmed per route to keep payloads small.
Cart state consistency
Cart lives on Shopify but must feel instant. Optimistic updates with server reconciliation bridged that gap.
Variant complexity
Products with multiple option dimensions need a selector that never lets a customer choose an unavailable combination.
Section 08
What I took away
- Headless is the right call when differentiation matters more than launch speed.
- Let the platform keep the parts that are dangerous to rebuild — checkout above all.
- GraphQL query design is a performance discipline, not just a data-fetching detail.
Model
Headless commerce
Framework
Hydrogen (Remix)
Data
Storefront + Admin GraphQL
Focus
Search, cart, shipping
Let's build something worth shipping
Available for freelance projects, full-time roles, and technical consulting. Tell me what you're building and I'll tell you honestly whether I'm the right person for it.
Based in Rio de Janeiro, Brazil · Working with teams in any timezone · Fluent in English and Portuguese