# Building a Headless Shopify Storefront with Builder.io: A Comprehensive Tutorial This report provides a step-by-step, production-ready guide for creating a **headless Shopify storefront** powered by [**Builder.io**](http://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. * [Building Headless Shopify with](https://shopify.tenten.co/building-headless-shopify-with-builderio-a-comprehensive-implementation-guide) [Builder.io](http://Builder.io)[: A Comprehensive Implementation Guide](https://shopify.tenten.co/building-headless-shopify-with-builderio-a-comprehensive-implementation-guide) * [The Ultimate Enterprise Guide to Shopify Headless: In-Depth Hydrogen Framework Analysis](https://shopify.tenten.co/the-ultimate-enterprise-guide-to-shopify-headless-in-depth-hydrogen-framework-analysis) --- ## 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**](http://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](http://Builder.io) as a visual CMS and data layer * Scaffold a Next.js frontend with Hydrogen or [Builder.io](http://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](http://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](http://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](http://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](http://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](http://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](http://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`](http://yourstore.myshopify.com)) --- ## Setting Up [Builder.io](http://Builder.io) ### Step 1: Create a [Builder.io](http://Builder.io) Account and Space 1. Go to [builder.io/signup](http://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](http://Builder.io) CLI To scaffold a new project: ```bash 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](http://Builder.io) space: ```bash builder create --key --name "Shopify Headless Store" ``` This will create a new space and link your local project to [Builder.io](http://Builder.io). --- ## Building the Frontend with Next.js and [Builder.io](http://Builder.io) SDK ### Step 1: Project Structure The scaffolded project includes: * `/pages` – Next.js pages * `/components` – Reusable React components * `/builder` – [Builder.io](http://Builder.io) SDK integration * `/lib/shopify` – Shopify API helpers ### Step 2: Configure Environment Variables Create a `.env.local` file: ```bash 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: ```ts // lib/shopify.ts export async function getProducts(): Promise { 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](http://Builder.io) Components Use the [Builder.io](http://Builder.io) React SDK to render dynamic content: ```tsx // 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 ; } ``` --- ## Modeling Content in [Builder.io](http://Builder.io) ### Step 1: Create a Product Page Template 1. In [Builder.io](http://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](http://Builder.io) [Builder.io](http://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: ```graphql 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](https://vercel.com) 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: ```bash npm create @shopify/hydrogen@latest ``` 2. Add [Builder.io](http://Builder.io) SDK to your Hydrogen app 3. 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](http://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](http://Builder.io) Targeting Engine [Builder.io](http://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](http://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](http://Builder.io) analytics --- ## Multilingual and Internationalization ### Shopify Markets Enable **Shopify Markets** to support multiple currencies and languages. Then: * Use [Builder.io](http://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](http://Builder.io) Permissions * Use **role-based access control** in [Builder.io](http://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](http://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](http://Builder.io) not syncing | Incorrect store domain | Ensure `.`[`myshopify.com`](http://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**](http://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 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 * Shopify. (2025). *What Is Headless Commerce: A Complete Guide for 2025*. Retrieved from [https://www.shopify.com/enterprise/blog/headless-commerce](https://www.shopify.com/enterprise/blog/headless-commerce) * Tenten. (2024). *Shopify 無頭電商指南*. Retrieved from [https://tenten.co/d2c/shopify-headless-guide/](https://tenten.co/d2c/shopify-headless-guide/) * [Builder.io](http://Builder.io). (2024). *Setting Up the Shopify Plugin*. Retrieved from [https://www.builder.io/c/docs/shopify-plugin](https://www.builder.io/c/docs/shopify-plugin) * [Builder.io](http://Builder.io). (2024). *Streamlining Content with* [*Builder.io*](http://Builder.io) *Headless CMS*. Retrieved from [https://www.amitechgrp.com/blog/a-headless-cms-meets-visual-editing-streamlining-content-with-builder-io](https://www.amitechgrp.com/blog/a-headless-cms-meets-visual-editing-streamlining-content-with-builder-io) * [Builder.io](http://Builder.io). (2024). *Headless CMS for Shopify's Hydrogen*. Retrieved from [https://www.builder.io/m/hydrogen-cms](https://www.builder.io/m/hydrogen-cms) * [Builder.io](http://Builder.io). (2024). *Ship Faster with Shopify and Builder*. Retrieved from [https://www.builder.io/m/shopify](https://www.builder.io/m/shopify) * [Headless - Tenten Commerce | Shopify Plus and B2B Expert](https://tenten.co/d2c/tag/headless/) * [Shopify Headless 企業級指南：Hydrogen 框架 (2025)](https://tenten.co/d2c/shopify-headless-hydrogen-2025/) * [商業巧思：把 Shopify 當作 CMS，用最低成本打造高效能網站！](https://tenten.co/d2c/shopify-as-low-cost-cms/) * [Shopify Headless 2025：解鎖電商潛能，釋放品牌無限可能](https://tenten.co/d2c/shopify-headless-2025/) * [Shopify Headless 無頭電商成本與開發時間完整解析 \[2025\]](https://tenten.co/d2c/shopify-headless-development-cost/) * [builder.io](http://builder.io) [](https://www.google.com/search?q=builder.io+tenten.co&oq=builder.io+tenten.co&gs_lcrp=EgZjaHJvbWUyBggAEEUYOTIJCAEQABgNGIAEMggIAhAAGA0YHjIICAMQABgNGB4yCAgEEAAYDRgeMgYIBRBFGDwyBggGEEUYPDIGCAcQRRg80gEIMzEzMmowajeoAgCwAgA&sourceid=chrome&ie=UTF-8&num=100)[tenten.co](http://tenten.co) [- Google Search](https://www.google.com/search?q=builder.io+tenten.co&oq=builder.io+tenten.co&gs_lcrp=EgZjaHJvbWUyBggAEEUYOTIJCAEQABgNGIAEMggIAhAAGA0YHjIICAMQABgNGB4yCAgEEAAYDRgeMgYIBRBFGDwyBggGEEUYPDIGCAcQRRg80gEIMzEzMmowajeoAgCwAgA&sourceid=chrome&ie=UTF-8&num=100) * [Builder.io](http://Builder.io) [全方位指南：視覺化開發平台的完整剖析](https://tenten.co/learning/builder-io-intro/) * [Builder.io](http://Builder.io) [與現有網站框架的整合指南 - topics - Tenten AI](https://university.tenten.co/t/builder-io/1713)