storehabit.com

E-commerce tutorials, Shopify alternatives, headless commerce for SMBs

Set Up Headless Shopify With a Custom Frontend

by Emma Rodriguez
Set Up Headless Shopify With a Custom Frontend

Picture this: your Shopify store is doing okay, but every time you want to tweak the homepage layout or speed up the product page, you're wrestling with Liquid templates and theme limitations. A developer friend mentions "going headless" and suddenly you're down a rabbit hole of acronyms — Storefront API, Next.js, CDN edge rendering — wondering if any of it is worth it for a store your size.

Here's the honest answer: headless Shopify is genuinely powerful, but it's also a real commitment. Before you spin up a single repo, you need to know what you're signing up for. This guide walks you through exactly how to set up headless Shopify with a custom frontend, what it costs in time and money, and whether the trade-offs make sense for where your store is right now.

What "Headless Shopify" Actually Means

In a traditional Shopify setup, the backend (products, orders, checkout) and the frontend (what shoppers see) are bundled together inside your theme. Headless separates those two layers. Shopify keeps doing what it's great at — inventory, payments, fulfillment — while a completely separate frontend application handles the visual experience.

That frontend talks to Shopify through the Storefront API, a GraphQL interface that lets you query products, collections, cart data, and more. Your custom site can be built in Next.js, Nuxt, Astro, SvelteKit, or any framework you prefer. Shopify never cares. It just answers API calls.

The practical upside: your frontend loads from a CDN edge, not Shopify's servers, so pages can hit sub-second load times. You get full design freedom — no theme constraints, no section schema gymnastics. The downside: you own the frontend code, which means you own its bugs, its hosting bill, and its maintenance.

Is Your Store Ready for This?

Before you spend a weekend setting this up, run a quick gut check.

You're probably a good candidate if:

  • You're doing at least $20K–$30K/month and page speed is measurably hurting conversion (even a 1-second delay can drop conversions by 7%, per Akamai's oft-cited research).
  • You need a truly custom UI that no theme can deliver — think interactive product configurators, heavy animation, or a deeply branded editorial experience.
  • You have a developer on staff or a reliable freelancer you can call.

You might want to wait if:

  • You're under $10K/month and still iterating on product-market fit. A fast, well-configured theme (Dawn, Prestige, Turbo) will outperform a half-finished headless build every time.
  • You rely heavily on Shopify apps that inject scripts into the storefront. Many third-party apps — reviews, loyalty, upsells — break or require significant re-integration in a headless setup.

Ask yourself: am I limited by Shopify's frontend, or am I limited by something else? Be honest. A lot of stores that "go headless" discover the bottleneck was actually their offer, not their theme.

The Core Setup: Step by Step

Assuming you've decided to move forward, here's the practical path.

1. Enable the Storefront API

In your Shopify admin, go to Settings → Apps and sales channels → Develop apps. Create a new app (name it something like "Headless Frontend"), then under API credentials, configure the Storefront API scopes you need. At minimum you'll want:

  • unauthenticated_read_product_listings
  • unauthenticated_read_collection_listings
  • unauthenticated_write_checkouts
  • unauthenticated_read_customer_tags (if you do personalization)

Save and grab your Storefront API access token — you'll need it in every API call your frontend makes.

2. Scaffold Your Frontend

Next.js is the most common choice right now, and for good reason: it handles server-side rendering, static generation, and edge functions in one framework, and there's a large community of headless Shopify examples to learn from.

Run npx create-next-app@latest my-store-frontend and you have a starting point. From there, install a GraphQL client — graphql-request is lightweight and works well, or you can use Apollo Client if you prefer a more structured cache layer.

Create a simple utility file that wraps your Storefront API calls:

const endpoint = `https://your-store.myshopify.com/api/2024-01/graphql.json`;
const headers = {
  'Content-Type': 'application/json',
  'X-Shopify-Storefront-Access-Token': process.env.SHOPIFY_STOREFRONT_TOKEN,
};

Store your token in an environment variable, never hardcoded. This is the single most common security mistake I see in early headless builds.

3. Build Your Product and Collection Pages

Start small. Don't try to rebuild your entire store in week one. Get a working product page first:

  • Query a product by handle using productByHandle
  • Render title, description, price, and images
  • Add a working "Add to Cart" mutation

Shopify's cart API (introduced in 2022) is significantly easier to work with than the old checkout API. Use cartCreate and cartLinesAdd mutations to manage the cart state, and store the cart ID in a cookie or localStorage.

Collection pages come next. Use collection queries with pagination — Shopify's Storefront API uses cursor-based pagination, so plan for first, after, last, and before arguments rather than simple page numbers.

4. Handle Checkout

This is where a lot of headless builds trip up. Shopify's native checkout is a hosted page at your-store.myshopify.com/checkouts/.... In a headless setup, you redirect shoppers there when they're ready to buy.

The good news: Shopify Checkout is fast, conversion-optimized, and handles taxes, shipping, and payment processing without you touching any of it. You don't need to rebuild checkout from scratch — and you really shouldn't. Custom checkout is only available on Shopify Plus ($2,000+/month), and even then it's a significant engineering project.

For most headless stores, the flow is: custom frontend cart → redirect to Shopify-hosted checkout → Shopify handles the rest. Clean and simple.

5. Deploy and Connect Your Domain

Deploy your frontend to Vercel or Netlify — both have generous free tiers and handle Next.js well. Vercel's free plan supports up to 100GB bandwidth/month, which covers most small stores comfortably.

Then point your primary domain (say, www.yourstore.com) to your new frontend's deployment URL. In Shopify admin, update your domain settings so Shopify knows your primary storefront is external. Your Shopify admin URL (yourstore.myshopify.com) stays active for backend management.

If you want your blog or certain pages to still run on Shopify (using native Liquid), you can proxy specific routes — /blogs/*, for example — back to Shopify using Next.js rewrites. That's an advanced move, but it saves you from rebuilding a blog CMS on day one.

A Quick Real-World Example

A candle brand I know — about $45K/month in revenue — made this switch last year. Their main pain point was a product customization flow (choose scent, vessel, label) that no Shopify app handled gracefully. Their theme was doing six app script injections just to fake a configurator, and their mobile page speed score sat at 38.

They spent roughly six weeks building a Next.js frontend with a custom configurator component. Post-launch, their mobile score jumped to 81, and their add-to-cart rate on the product page improved by 14%. Total cost: about $8,000 in developer time, plus roughly $20/month in hosting.

Was it worth it? For them, yes — the configurator was a genuine competitive advantage. For a store selling straightforward products with a clean theme, probably not.

Three Things You Can Do Today

If you want to start moving toward a headless Shopify setup without committing to a full rebuild, here are three concrete actions:

  1. Audit your current app stack. List every Shopify app you use and check whether it offers a headless-compatible integration or JavaScript SDK. Apps with no API layer will need to be replaced or rebuilt. Knowing this upfront saves painful surprises later.

  2. Create a development app and call the Storefront API manually. Use a tool like Insomnia or Postman to run a simple products query against your store. Seeing real data come back from your own store makes the whole concept click — and it takes about 20 minutes.

  3. Clone a headless Shopify starter and run it locally. Shopify maintains an open-source starter called Hydrogen (built on Remix), and the community has Next.js starters on GitHub. Spend an hour poking around one. You'll quickly get a feel for whether the complexity matches your team's capacity.

None of these steps commit you to anything. They just give you real information instead of abstract anxiety.

Wrapping Up

Setting up headless Shopify with a custom frontend is absolutely doable — even for a small team — but it works best when you have a specific problem that a traditional theme genuinely can't solve. Speed, design freedom, and complex interactivity are all legitimate reasons. "I heard it's better" is not.

If you've done the gut check and you're ready to build, start with the Storefront API and one working product page. Resist the urge to architect everything upfront. Get something real in front of customers fast, then iterate.

Your next step: spend 20 minutes today creating a Shopify development app and firing your first Storefront API query. That single action will tell you more than any amount of reading — including this article.