A production-ready starter template for building headless Shopify storefronts with Next.js. Includes a complete Shopify Storefront API integration with GraphQL queries, mutations, cart management, product/page fetching, and webhook-based revalidation — all fully typed with TypeScript.
- Next.js 16 — App Router, Server Actions, Turbopack
- React 19 — with React Compiler for automatic memoization
- TypeScript 5 — strict mode
- Shopify Storefront API — GraphQL (2025-04)
- Tailwind CSS 4 — utility-first styling
- Zod 4 — runtime environment variable validation
- Bun — package manager and runtime
- Prettier — code formatting
- ESLint — linting with Next.js config
├── lib/shopify/
│ ├── client.ts # Storefront API client (server-only)
│ ├── products.ts # getAllProducts(), getProductByHandle()
│ ├── pages.ts # getPages(), getPage()
│ ├── cart.ts # getCart(), createCart(), addToCart(), updateCartItems(), removeFromCart()
│ ├── fragments/ # GraphQL fragments (image, seo, product, page, cart)
│ ├── queries/ # GraphQL queries (product, page, cart)
│ └── mutations/ # GraphQL mutations (cart CRUD)
├── components/
│ ├── cart/
│ │ ├── cart-provider.tsx # CartProvider context + useCart() hook
│ │ └── actions.ts # Server actions with cookie-based cart persistence
│ └── product/
│ └── product-provider.tsx # ProductProvider context + useProduct() hook
├── types/
│ └── shopify.ts # TypeScript types (Product, Cart, Page, Variant, etc.)
├── app/api/revalidate/
│ └── route.ts # Shopify webhook endpoint for ISR revalidation
├── lib/
│ ├── utils.ts # cn(), transformEdgeNode(), handleGraphQLResponse(), formatPrice()
│ └── constants.ts # Shared constants
├── env.ts # Zod env validation + global type augmentation
├── .env.example # Environment variable template
└── .graphqlrc.ts # Shopify GraphQL codegen config
bun installcp .env.example .env.localFill in your Shopify credentials:
| Variable | Description |
|---|---|
SHOPIFY_STORE_DOMAIN |
Your .myshopify.com domain |
SHOPIFY_STOREFRONT_ACCESS_TOKEN |
Public Storefront API access token |
SHOPIFY_REVALIDATION_SECRET |
Secret for webhook revalidation |
You can generate a Storefront API token in your Shopify Admin under Settings > Apps and sales channels > Develop apps > Storefront API.
bun run devOpen http://localhost:3000 to see the result.
bun run graphql-codegenTo enable on-demand revalidation when products or collections change in Shopify:
- Go to Shopify Admin > Settings > Notifications > Webhooks
- Add webhooks for
products/create,products/update,products/delete - Set the URL to:
https://your-domain.com/api/revalidate?secret=YOUR_REVALIDATION_SECRET
Deploy to Vercel with one click:
Or build for production:
bun run build
bun run startMIT License
Copyright (c) 2025
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.