Building a Headless Shopify Storefront with Builder.io: A Comprehensive Tutorial

Erik ChenErik Chen
9 min read

This report provides a step-by-step, production-ready guide for creating a headless Shopify storefront powered by Builder.io. It synthesizes the latest technical documentation, best practices, and real-world examples to help developers, marketers, and e-commerce teams launch a high-performance, scalable, and visually editable online store. The tutorial is structured to take you from zero to a fully deployed headless commerce experience, with deep dives into architecture, tooling, content modeling, performance optimization, and ongoing operations.

Summary of Key Findings

Headless commerce decouples the frontend presentation layer from the backend commerce logic, enabling teams to deliver faster, more personalized, and omnichannel shopping experiences. By combining Shopify’s robust commerce APIs with Builder.io’s visual CMS, teams can empower marketers to iterate on content without developer bottlenecks while still retaining full control over the tech stack. This tutorial outlines how to:

  • Set up a Shopify store for headless access

  • Configure Builder.io as a visual CMS and data layer

  • Scaffold a Next.js frontend with Hydrogen or Builder.io SDKs

  • Model products, collections, and landing pages visually

  • Deploy to Vercel or Oxygen with CI/CD

  • Optimize for performance, SEO, and personalization at scale

Architecture Overview: Shopify + Builder.io in Headless Mode

Understanding the Decoupled Stack

In a traditional Shopify setup, the frontend (theme) and backend (admin, checkout, APIs) are tightly coupled. In a headless architecture, the frontend is a standalone application—often built with React, Next.js, or Vue—that communicates with Shopify via the Storefront API and Admin API. Builder.io acts as the content management and presentation layer, enabling non-technical users to create and manage pages, layouts, and components visually.

This separation allows for:

  • Frontend flexibility: Use any framework or device (web, mobile, IoT)

  • Backend stability: Shopify continues to handle checkout, payments, inventory, and orders

  • Content agility: Builder.io enables drag-and-drop editing, A/B testing, and personalization without code changes

Core Components of the Stack

LayerTechnology StackResponsibility
FrontendNext.js + React + Tailwind CSSSSR/SSG, routing, UI components, performance
CMSBuilder.ioVisual editing, content modeling, personalization, A/B testing
Commerce APIShopify Storefront API (GraphQL)Product data, collections, cart, checkout
HostingVercel or Shopify OxygenEdge deployment, CDN, CI/CD
Dev ToolsHydrogen (optional), GitHub ActionsLocal dev, testing, deployment pipelines

Preparing Shopify for Headless Access

Step 1: Enable Custom Apps

To allow Builder.io to read product and collection data, you must create a custom app in Shopify:

  1. From your Shopify admin, go to Settings > Apps and sales channels

  2. Click Develop apps > Create an app

  3. Name it “Builder.io Integration”

  4. Under API credentials, click Configure Admin API scopes

  5. Enable the following scopes:

    • read_products

    • read_collections

    • read_orders

    • read_customers

  6. Save and Install app

  7. Copy the Admin API access token and Storefront access token

Step 2: Configure Storefront API

The Storefront API is used by the frontend to fetch product data without exposing sensitive admin data. Ensure the following:

  • Enable the Storefront API in your custom app

  • Set the correct permissions for unauthenticated access

  • Copy the Storefront access token and store domain (e.g., yourstore.myshopify.com)

Setting Up Builder.io

Step 1: Create a Builder.io Account and Space

  1. Go to builder.io/signup and create a free account

  2. Create a new space for your Shopify project

  3. From the dashboard, go to Integrations > Shopify

  4. Click Enable, then Configure

  5. Enter your store domain and Storefront access token

  6. Click Connect Your Shopify Custom App

Step 2: Install the Builder.io CLI

To scaffold a new project:

npm install -g @builder.io/cli
git clone https://github.com/BuilderIO/nextjs-shopify.git
cd nextjs-shopify
npm install

Then initialize your Builder.io space:

builder create --key <your-private-key> --name "Shopify Headless Store"

This will create a new space and link your local project to Builder.io.

Building the Frontend with Next.js and Builder.io SDK

Step 1: Project Structure

The scaffolded project includes:

  • /pages – Next.js pages

  • /components – Reusable React components

  • /builder – Builder.io SDK integration

  • /lib/shopify – Shopify API helpers

Step 2: Configure Environment Variables

Create a .env.local file:

SHOPIFY_STOREFRONT_API_TOKEN=your_storefront_token
SHOPIFY_STORE_DOMAIN=yourstore.myshopify.com
BUILDER_API_KEY=your_builder_public_key

Step 3: Fetch Shopify Data

Use the Shopify Storefront API to fetch products and collections:

// lib/shopify.ts
export async function getProducts(): Promise<Product[]> {
  const res = await fetch(SHOPIFY_GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'X-Shopify-Storefront-Access-Token': process.env.SHOPIFY_STOREFRONT_API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        {
          products(first: 10) {
            edges {
              node {
                id
                title
                handle
                images(first: 1) {
                  edges {
                    node {
                      url
                    }
                  }
                }
              }
            }
          }
        }
      `,
    }),
  });
  const json = await res.json();
  return json.data.products.edges.map((edge: any) => edge.node);
}

Step 4: Integrate Builder.io Components

Use the Builder.io React SDK to render dynamic content:

// pages/[...page].tsx
import { builder, BuilderComponent } from '@builder.io/react';
import { GetStaticProps } from 'next';

builder.init(process.env.BUILDER_API_KEY);

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const page = await builder.get('page', { url: '/' }).promise();
  return { props: { page: page || null }, revalidate: 10 };
};

export default function Page({ page }) {
  return <BuilderComponent model="page" content={page} />;
}

Modeling Content in Builder.io

Step 1: Create a Product Page Template

  1. In Builder.io, go to Models > + New Model

  2. Choose Page type

  3. Name it “Product Page”

  4. Add fields:

    • productHandle (text)

    • customDescription (rich text)

    • heroImage (file)

Step 2: Use Shopify Data in Builder.io

Builder.io can pull live Shopify data using data bindings:

  • Add a Data tab in your model

  • Use Shopify GraphQL to bind product data to components

  • Example query:

query ($handle: String!) {
  product(handle: $handle) {
    title
    description
    images(first: 1) {
      edges {
        node {
          url
        }
      }
    }
  }
}

Step 3: Create Landing Pages Visually

Marketers can now:

  • Drag and drop components (hero, product grid, testimonials)

  • Bind Shopify products dynamically

  • Schedule content changes

  • Run A/B tests without developer help

Deployment and Hosting

Option 1: Deploy to Vercel

  1. Push your code to GitHub

  2. Import the repo in Vercel

  3. Add environment variables in Vercel dashboard

  4. Deploy – Vercel will automatically build and serve your site at the edge

Option 2: Deploy to Shopify Oxygen (Hydrogen)

If using Hydrogen:

  1. Install Hydrogen CLI:
npm create @shopify/hydrogen@latest

  1. Add Builder.io SDK to your Hydrogen app

  2. Deploy via GitHub Actions to Oxygen

Performance Optimization

Image Optimization

  • Use Shopify’s CDN for product images

  • Enable Next.js Image component with priority for above-the-fold images

  • Use Builder.io’s built-in lazy loading for below-the-fold content

Caching Strategy

  • Use ISR (Incremental Static Regeneration) in Next.js for product pages

  • Cache GraphQL responses with Redis or Vercel Edge Config

  • Set proper Cache-Control headers for static assets

Core Web Vitals

MetricTargetHow to Achieve
LCP<2.5sPreload hero images, use SSR
FID<100msMinimize JS, use web workers
CLS<0.1Reserve image space, avoid layout shift

Personalization and A/B Testing

Builder.io Targeting Engine

Builder.io allows you to:

  • Target users by device, location, or behavior

  • Create personalized banners and product recommendations

  • Run A/B tests on landing pages and product descriptions

Example: Personalized Hero Banner

  1. Create a Hero Banner component in Builder.io

  2. Add targeting rules:

    • If user.location === 'US', show July 4th promo

    • If user.device === 'mobile', show mobile-optimized layout

  3. Measure performance via Builder.io analytics

Multilingual and Internationalization

Shopify Markets

Enable Shopify Markets to support multiple currencies and languages. Then:

  • Use Builder.io’s locale targeting to serve localized content

  • Create separate models for each language or use field-level translations

  • Sync product data with translated content via Shopify’s GraphQL API

Security and Access Control

API Security

  • Never expose Admin API tokens in the frontend

  • Use server-side functions to proxy sensitive requests

  • Rotate Storefront API tokens periodically

Builder.io Permissions

  • Use role-based access control in Builder.io

  • Limit content editing to specific models or pages

  • Enable approval workflows for publishing

Maintenance and Scaling

CI/CD Pipeline

Use GitHub Actions to:

  • Run tests on pull requests

  • Deploy to staging and production

  • Invalidate CDN cache on deployment

Monitoring

  • Use Vercel Analytics or ShopifyQL for performance insights

  • Monitor Builder.io usage and content performance

  • Set up alerts for API rate limits or errors

Troubleshooting Common Issues

IssueCauseSolution
Products not showingMissing Storefront API scopesRe-check token permissions
Builder.io not syncingIncorrect store domainEnsure .myshopify.com format
Slow page loadsLarge image assetsUse Shopify CDN + lazy loading
Checkout errorsMisconfigured domainsAdd frontend domain to Shopify checkout settings

Conclusion and Next Steps

This tutorial has walked you through the complete process of building a headless Shopify storefront with Builder.io, from initial setup to deployment and optimization. The architecture you now have is:

  • Scalable: Add new channels (mobile app, kiosk, POS) without backend changes

  • Fast: Optimized for Core Web Vitals and SEO

  • Flexible: Marketers can iterate without developers

  • Future-proof: Composable stack ready for new technologies

  1. Extend the CMS: Add blog, lookbooks, or campaign landing pages

  2. Integrate CDP: Connect Segment or Klaviyo for deeper personalization

  3. Add Subscriptions: Use Shopify’s Subscription APIs for recurring revenue

  4. Launch Mobile App: Use the same backend to power a React Native app

References

0
Subscribe to my newsletter

Read articles from Erik Chen directly inside your inbox. Subscribe to the newsletter, and don't miss out.

headless cmsheadlessshopifyHeadless Commercebuilder.io

Written by

Erik Chen
Erik Chen