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
| Layer | Technology Stack | Responsibility |
| Frontend | Next.js + React + Tailwind CSS | SSR/SSG, routing, UI components, performance |
| CMS | Builder.io | Visual editing, content modeling, personalization, A/B testing |
| Commerce API | Shopify Storefront API (GraphQL) | Product data, collections, cart, checkout |
| Hosting | Vercel or Shopify Oxygen | Edge deployment, CDN, CI/CD |
| Dev Tools | Hydrogen (optional), GitHub Actions | Local 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:
From your Shopify admin, go to Settings > Apps and sales channels
Click Develop apps > Create an app
Name it “Builder.io Integration”
Under API credentials, click Configure Admin API scopes
Enable the following scopes:
read_products
read_collections
read_orders
read_customers
Save and Install app
Copy the Admin API access token and Storefront access token
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)
Step 1: Create a Builder.io Account and Space
Go to builder.io/signup and create a free account
Create a new space for your Shopify project
From the dashboard, go to Integrations > Shopify
Click Enable, then Configure
Enter your store domain and Storefront access token
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
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:
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} />;
}
Step 1: Create a Product Page Template
In Builder.io, go to Models > + New Model
Choose Page type
Name it “Product Page”
Add fields:
Step 2: Use Shopify Data in Builder.io
Builder.io can pull live Shopify data using data bindings:
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
Push your code to GitHub
Import the repo in Vercel
Add environment variables in Vercel dashboard
Deploy – Vercel will automatically build and serve your site at the edge
Option 2: Deploy to Shopify Oxygen (Hydrogen)
If using Hydrogen:
- Install Hydrogen CLI:
npm create @shopify/hydrogen@latest
Add Builder.io SDK to your Hydrogen app
Deploy via GitHub Actions to Oxygen
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
| Metric | Target | How to Achieve |
| LCP | <2.5s | Preload hero images, use SSR |
| FID | <100ms | Minimize JS, use web workers |
| CLS | <0.1 | Reserve image space, avoid layout shift |
Personalization and A/B Testing
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
Create a Hero Banner component in Builder.io
Add targeting rules:
If user.location === 'US', show July 4th promo
If user.device === 'mobile', show mobile-optimized layout
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
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
| Issue | Cause | Solution |
| Products not showing | Missing Storefront API scopes | Re-check token permissions |
| Builder.io not syncing | Incorrect store domain | Ensure .myshopify.com format |
| Slow page loads | Large image assets | Use Shopify CDN + lazy loading |
| Checkout errors | Misconfigured domains | Add 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
Recommended Next Steps
Extend the CMS: Add blog, lookbooks, or campaign landing pages
Integrate CDP: Connect Segment or Klaviyo for deeper personalization
Add Subscriptions: Use Shopify’s Subscription APIs for recurring revenue
Launch Mobile App: Use the same backend to power a React Native app
References
