Headless Shopify starter built on Next.js 🤘
Headless CMS powered by Sanity.io ⚡

Features • Tours • Set Up • Spin Up • Deployment • Extras

✨ Features

Utility-first CSS with Tailwind CSS
Animations powered by Framer Motion
Cart powered by Shopify Buy SDK
Real-time inventory check for products using SWR
Klaviyo waitlist form for out-of-stock products
Klaviyo newsletter form with opt-in field
Dynamic Page Routes for custom page creation
Automatic Sitemap.xml generation
Automatic robots.txt generation
Automatic 301 Redirects from Sanity
Live Preview content directly from Sanity
Modern Image component using Sanity's Hotspot, Crop, and automatic WEBP format
Modular page content for all pages, including dynamic grid layouts
Customizable Promotion Banner
Customizable Cookie Notice
Accessibility features:
- ARIA Landmark Roles
- Default focus states preserved for keyboard navigation
- Correctly trap focus for drawers with focus-trap-react
- Roving tabindex for radio buttons
- Input-based quantity counters
- Required alt text for all images
- "Skip to Content" link
SEO features:
- Page-level SEO/Share settings with previews
- Fallback Global SEO/Share settings
- Automatic JSON-LD Schema markup for products

Shopify Integration Features

Automatically syncs products from Shopify into Sanity
Custom action to sync product cart thumbnails back to Shopify from Sanity
Tracks product status (draft/published) from Shopify to help control visibility while editing
Deleted products and variants are preserved and flagged in Sanity
Updates the URL on variant changes while keeping a clean history stack
Vanity shop URL masking
Global Cart with access to all variant data for line items
Supports Single Variant products out of the box
Product photo galleries with variant granularity
Dynamic /shop collection page
Custom collection pages
Ability to surface a variant option on product cards

🎧 Tours

Still not sold? Here's some videos to get you psyched:

Famous 5-Minute Setup™ - Coming Soon
From sync to sale, watch me spin up a fresh storefront in under 5 minutes!

Explore the file Structure - Coming Soon
In-depth look at the file structure, naming conventions, and logic under the hood

Setting up your first Product - Coming Soon
Explore the Product settings within Sanity and how to properly setup PDP pages and PLP cards

Connecting to Klaviyo and testing your Forms - Coming Soon
Learn how to quickly connect Klaviyo to utilize product waitlist and newsletter forms

Setup your first Vercel deployment - Coming Soon
Using the Sanity Vercel Deploy plugin, see how easy it is to empower your clients to trigger deploys

🔥 Automatic Set Up

Quickly deploy as a Sanity Starter on Vercel with a pre-populated store! All you have to do is connect Shopify (follow step 2 and 3 below)

💀 Manual Set Up

Clone this repository from your GitHub account with the Use this template button

1) Sanity

If you don't have the Sanity CLI installed, first run npm install -g @sanity/cli to install it globally
npm install && sanity init in the /studio folder
During Sanity's initalization it will warn you, type Y and hit enter:

? The current folder contains a configured Sanity studio. Would you like to reconfigure it? (Y/n)

When it asks you what dataset configuration to use, go with the default
Add CORS Origins to your newly created Sanity project (visit: manage.sanity.io and go to Settings > API):
- Add your Studio URLs with credentials: http://localhost:3333 and [subdomain].sanity.studio
- Add your front-end URLs without credentials: http://localhost:3000 and https://[subdomain].vercel.app

⚠️ Important!
For "singleton" documents, like settings sections, the schema uses a combination of __experimental_actions and the new actions resolver. If you are using this outside of the official Sanity Starter, you will need to comment out the __experimental_actions line in "singleton" schemas to publish settings for the first time. This is because a singleton is still a document type, and one needs to exist first before it can be edited. Additionally, if you want to create additional "singleton" schemas, be sure to edit the singletons array in the following file: /studio/parts/resolve-actions.js.

2) Shopify Storefront Access

Enable Private Apps in Shopify
- Apps > "Manage Private Apps" (text link in page footer)
- Enable Private Apps
Create new Private App
- Apps > Manage Private Apps > "Create private app"
- Give this a relevant name, I prefer: "Headless Storefront", so it's clear what it's being used for
- Use your dev email to know when there are issues
- Change Admin API permissions on "Products" to Read and write
- Allow this app to access your storefront data using the Storefront API, with at least the following permissions:
  - Read inventory of products and their variants
  - Read and modify checkouts

3) Shopify Webhooks

Go to "Settings" (bottom left) -> "Notifications" -> "Webhooks" (very bottom)
add the following webhooks:

product creation - [your-domain]/api/shopify/product-update
product update - [your-domain]/api/shopify/product-update
product deletion - [your-domain]/api/shopify/product-delete

⚠️ Note
You have to use a real domain name (no localhost). Be sure to use your Vercel project URL during development, and then switch to the production domain once live. You won't know your Vercel project domain until you deploy in a later step, just enter in what you think it will be for now!

4) NextJS

npm install in the project root folder on local
Create an .env.local file in the project folder, and add the following variables:

SANITY_PROJECT_DATASET=production
SANITY_PROJECT_ID=XXXXXX
SANITY_API_TOKEN=XXXXXX
SHOPIFY_STORE_ID=XXXXXX
SHOPIFY_API_TOKEN=XXXXXX
SHOPIFY_API_PASSWORD=XXXXXX
SHOPIFY_WEBHOOK_INTEGRITY=XXXXXX

// Needed for Klaviyo forms:
KLAVIYO_API_KEY=XXXXXX

// Needed for Mailchimp forms:
MAILCHIMP_API_KEY=XXXXXX-usX
MAILCHIMP_SERVER=usX

// Needed for SendGrid forms:
SENDGRID_API_KEY=XXXXXX

// Needed for Google Tag Manager:
GTM_ID=XXX-XXXXXX

Update all the XXXXXX values, here's where to find each:

SANITY_PROJECT_ID - You can grab this after you've initalized Sanity, either from the studio/sanity.json file, or from your Sanity Manage dashboard
SANITY_API_TOKEN - Generate an API token for your Sanity project. Access your project from the Sanity Manage dashboard, and navigate to: "Settings" -> "API" -> "Add New Token" button. Make sure you give read + write access!
SHOPIFY_STORE_ID - This is your Shopify store ID, it's the subdomain behind .myshopify.com
SHOPIFY_API_TOKEN - Copy the Storefront Access Token you copied from setting up your Private Shopify App. (Note: This is not the Admin API Key, scroll to the bottom where it says "Storefront API" for the correct value)
SHOPIFY_API_PASSWORD - Copy the Admin API password from "Apps" -> "Manage private apps" -> [your_private_app].
SHOPIFY_WEBHOOK_INTEGRITY - Copy the Integrity hash from "Settings" -> "Notifications" -> "Webhooks" (very bottom of page)
KLAVIYO_API_KEY - This is your Public API Key / Site ID from your Klaviyo Account "Settings" -> "API Keys"
MAILCHIMP_API_KEY - Create an API key from "Account -> "Extras" -> API Keys
MAILCHIMP_SERVER - This is the server your account is from. It's in the URL when logged in and at the end of your API Key
SENDGRID_API_KEY - Create an API key from "Settings" -> "API Keys" with "Restricted Access" to only "Mail Send"
GTM_ID - If using Google Tag Manager this is your Container ID

5) Shopify Store Theme

Since we're serving our store through a headless environment, we don't want visitors accessing our unused shopify theme. The domain for this is visible during checkout, and is publicly accessible. To silence it, replace your current theme's theme.liquid file with the one from this repo, and replace YOUR_STOREFRONT_DOMAIN_NO_PROTOCOL with your actual frontsite domain URL (do not include protocol or trailing slash)

This will essentially "pass-through" URLs accessed at your Shopify Store to your true headless storefront (ie. shop.hull.dev/products -> hull.dev/products)

⚡ Spin Up

Next (Front End)

npm run dev in the project folder to start the front end locally

Your front end should be running on http://localhost:3000

Sanity (Back End)

sanity start in the /studio folder to start the studio locally

Your Sanity Studio should be running on http://localhost:3333

🚀 Deployment

Vercel

This is setup to work seamlessly with Vercel, which I highly recommend as your hosting provider of choice. Simply follow the on-screen instructions to setup your new project, and be sure to add the same .env.local variables to your Vercel Project

Sanity

This is an easy one, you can simply run sanity deploy from the /studio folder in your project. Select a subdomain you want; your Studio is now accessible from the web. This is where I'll invite the client to manage the project so they can both add billing info and begin editing content.

Client Updates

Once you hand off to the client you'll want to give them the ability to generate builds when they make updates within the Sanity Studio. The easiest way to do this is through my Vercel Deploy plugin.

🤘 Extras/Tips

This looks like a theme... How can I use this like a starter?

While this starter is relatively opinionated, the goal was three-fold:

Use high-quality packages that don't get in the way
Solve common UX problems and complex logic so you can focus on the fun stuff
Create a more approachable starter for anyone looking to build production-ready headless Shopify experiences

That being said, I understand this means a lot of what's included is very opinionated. However, you'll find that at it's core the structure and naming conventions lend itself to really making it your own.

By now, I'm sure you noticed the ridiculous-looking demo site (I love 90's metal, can you tell?)

I've purposefully used extracted component classes, not only for cleaner file structure, but also so you can easily work in your own styles exclusively within the styles folder. Feel free to extend our outright remove the applied styles for all the components!

What's up with the CSS? What are extracted component classes and why should I use them?

While utility-first CSS definitely speeds up your dev time, it can become overwhelming and untenable. This can make it difficult to understand what a component is doing when shrouded in dozens of utility classes, especially for developers getting familiar with a new codebase. Luckily, Tailwind offers the ability to extract a component, allowing you to compose custom utility patterns.

The nice thing about this is we can get all the benefits of writing in utility class shorthand, but without having to sift through all your javascript logic to adjust styles. This means writing our CSS is business as usual. You create stylesheets, but use Tailwind's @apply to create nice and succinct classes to push to your components.

You still get all the tree-shaking benefits of Tailwind, and you can still use utility classes in your components when needed; the best of both worlds!

Can I use this for non-Shopify projects?

Absolutely! This starter was actually born out of a non-shopify starter I had been using for my own client projects.

I made a marketing-starter branch that is HULL without all the Shopify logic! The fastest way to get started is simply cloning that branch locally into an empty project folder:

git clone -b marketing-starter --single-branch git@github.com:ndimatteo/HULL.git .

You can read the setup instructions for this version from the branch's README.

Error: Failed to communicate with the Sanity API

If you get this error in your CLI, you need to logout and log back in again. Simply do sanity logout and then sanity login to fix.

Access your "product_sync" metafields in Shopify without using a plugin

Simply navigate directly to: https://[store_id].myshopify.com/admin/bulk?resource_name=Product&edit=metafields.sanity.product_sync

(making sure to replace [store_id] with your Shopify Store ID)

How do I properly hand-off a Vercel project to the client?

While not as easy as Netlify, what I prefer to do is:

Have the client create their own Vercel account
At the time of writing, Github connections can only be connected to one Vercel account at a time, so have the client create a Github account if they don't already have one, and transfer the project repo to them
Delete the dev project from your own Vercel account (this is so the client can utilize the project name and domain you were using during dev)
You or the client can now connect their newly transferred Github repo to their own Vercel account!

How can I see the bundle size of my website?

Simply run npm run analyze from the project folder. This will run a build of your site and automatically open the Webpack Bundle Analyzer visuals for your site's build files.

💯 Shoutouts

Huge ups to the following talented and rad folks who helped in countless ways. Thank you for all the support, code contributions, and discussions.

markSteph / HULL