Jamstack Storefront

Jamstack Storefront

Overview

A Jamstack storefront pre-renders catalog pages at build time for maximum performance and CDN cacheability, while using client-side JavaScript and commerce APIs for dynamic functionality (cart, checkout, account). Next.js with Incremental Static Regeneration (ISR) and Astro with on-demand rendering are the two dominant approaches, each offering different tradeoffs between build times, freshness, and interactivity. This skill covers setting up a Jamstack commerce site, managing catalog regeneration, and integrating headless commerce APIs.

When to Use This Skill

• When SEO and Core Web Vitals scores are top priorities — static HTML scores near-perfect Lighthouse results
• When you have a large catalog that rarely changes and want sub-100ms page loads from CDN
• When you want to decouple the commerce backend (Shopify, Saleor, commercetools) from the storefront deployment cycle
• When your team wants to use modern React/Astro tooling rather than a platform's proprietary theme system
• When you need to combine commerce data with a CMS (Contentful, Sanity) at build time

Prerequisites & Platform Notes

This skill is written for custom/headless storefronts (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

Shopify: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services. WooCommerce: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress. Magento: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

You'll need:

• Node.js 18+ (or adapt to your backend language)
• Redis for caching/queues
• An email sending service (SendGrid, AWS SES, or Postmark)
• CDN (Cloudflare, CloudFront, or Fastly)

Core Instructions

1. Bootstrap a Next.js commerce storefront

   npx create-next-app@latest my-store --typescript --tailwind --app
   cd my-store
   npm install @shopify/storefront-api-client graphql

Configure the Storefront API client:

   // lib/shopify.ts
   import {createStorefrontApiClient} from '@shopify/storefront-api-client';

   export const shopify = createStorefrontApiClient({
     storeDomain: process.env.SHOPIFY_STORE_DOMAIN!,
     publicAccessToken: process.env.SHOPIFY_STOREFRONT_TOKEN!,
     apiVersion: '2025-01',
   });

2. Statically generate product pages with ISR

   // app/products/[handle]/page.tsx (Next.js App Router)
   import {shopify} from '@/lib/shopify';
   import {notFound} from 'next/navigation';

   // ISR: revalidate every 60 seconds
   export const revalidate = 60;

   // Pre-build top products at build time
   export async function generateStaticParams() {
     const {data} = await shopify.request(TOP_PRODUCTS_QUERY, {
       variables: {first: 200},
     });
     return data.products.edges.map(({node}: any) => ({handle: node.handle}));
   }

   export default async function ProductPage({params}: {params: {handle: string}}) {
     const {data} = await shopify.request(PRODUCT_QUERY, {
       variables: {handle: params.handle},
     });

     if (!data.product) notFound();

     return <ProductDetail product={data.product} />;
   }

   const PRODUCT_QUERY = `
     query ProductByHandle($handle: String!) {
       product(handle: $handle) {
         id title descriptionHtml
         images(first: 5) { edges { node { url altText } } }
         variants(first: 20) {
           edges { node { id title price { amount currencyCode } availableForSale } }
         }
       }
     }
   `;

3. Build an Astro storefront for minimal JavaScript overhead

Astro ships zero JS by default — components are server-rendered to static HTML unless explicitly hydrated:

   npm create astro@latest -- --template minimal
   cd my-astro-store
   npx astro add tailwind
   npm install @astrojs/node graphql-request

   ---
   // src/pages/products/[handle].astro
   import {GraphQLClient, gql} from 'graphql-request';
   import Layout from '../../layouts/Layout.astro';
   import AddToCartButton from '../../components/AddToCartButton.tsx'; // Island

   export async function getStaticPaths() {
     const client = new GraphQLClient(import.meta.env.SALEOR_API_URL);
     const {products} = await client.request(gql`query { products(first: 200, channel: "default-channel") { edges { node { slug } } } }`);
     return products.edges.map(({node}: any) => ({params: {handle: node.slug}}));
   }

   const {handle} = Astro.params;
   const client = new GraphQLClient(import.meta.env.SALEOR_API_URL);
   const {product} = await client.request(PRODUCT_QUERY, {slug: handle, channel: 'default-channel'});
   ---

   <Layout title={product.name}>
     <h1>{product.name}</h1>
     <img src={product.thumbnail.url} alt={product.thumbnail.alt} />
     <!-- Only this interactive island ships JavaScript -->
     <AddToCartButton client:load variantId={product.variants[0].id} />
   </Layout>

4. Implement on-demand ISR webhooks for catalog freshness

When a product is updated in your CMS or commerce platform, trigger Next.js to revalidate only that page:

   // app/api/revalidate/route.ts
   import {NextRequest, NextResponse} from 'next/server';
   import {revalidatePath, revalidateTag} from 'next/cache';

   export async function POST(req: NextRequest) {
     const authHeader = req.headers.get('authorization');
     if (authHeader !== `Bearer ${process.env.REVALIDATION_TOKEN}`) {
       return NextResponse.json({error: 'Unauthorized'}, {status: 401});
     }

     const body = await req.json();
     const {type, handle, collectionHandle} = body;

     switch (type) {
       case 'product':
         revalidatePath(`/products/${handle}`);
         revalidateTag('products');
         break;
       case 'collection':
         revalidatePath(`/collections/${collectionHandle}`);
         revalidateTag('collections');
         break;
       case 'all':
         revalidateTag('products');
         revalidateTag('collections');
         break;
     }

     return NextResponse.json({revalidated: true, timestamp: Date.now()});
   }

Configure your commerce platform to POST to this endpoint on product updates.

5. Implement client-side cart with Zustand

Static product pages need client-side cart state. Use lightweight state management with localStorage persistence:

   // lib/cart-store.ts
   import {create} from 'zustand';
   import {persist} from 'zustand/middleware';

   interface CartItem {
     variantId: string;
     title: string;
     price: number;
     quantity: number;
     image: string;
   }

   interface CartStore {
     items: CartItem[];
     addItem: (item: CartItem) => void;
     removeItem: (variantId: string) => void;
     updateQuantity: (variantId: string, quantity: number) => void;
     clearCart: () => void;
     total: () => number;
   }

   export const useCartStore = create<CartStore>()(
     persist(
       (set, get) => ({
         items: [],
         addItem: (item) => set((state) => {
           const existing = state.items.find(i => i.variantId === item.variantId);
           if (existing) {
             return {items: state.items.map(i => i.variantId === item.variantId ? {...i, quantity: i.quantity + item.quantity} : i)};
           }
           return {items: [...state.items, item]};
         }),
         removeItem: (variantId) => set((state) => ({items: state.items.filter(i => i.variantId !== variantId)})),
         updateQuantity: (variantId, quantity) => set((state) => ({items: state.items.map(i => i.variantId === variantId ? {...i, quantity} : i)})),
         clearCart: () => set({items: []}),
         total: () => get().items.reduce((sum, item) => sum + item.price * item.quantity, 0),
       }),
       {name: 'cart-storage'},
     ),
   );

6. Configure CDN caching and cache purging

   // next.config.ts
   export default {
     async headers() {
       return [
         {
           source: '/products/:path*',
           headers: [
             {key: 'Cache-Control', value: 'public, s-maxage=60, stale-while-revalidate=600'},
           ],
         },
         {
           source: '/api/:path*',
           headers: [
             {key: 'Cache-Control', value: 'no-store'},
           ],
         },
       ];
     },
     images: {
       remotePatterns: [
         {protocol: 'https', hostname: '**.shopify.com'},
         {protocol: 'https', hostname: '**.saleor.io'},
       ],
     },
   };

Examples

Next.js 15 App Router with fetch caching tags

// lib/get-product.ts
export async function getProduct(handle: string) {
  const res = await fetch(`${process.env.SALEOR_API_URL}`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({query: PRODUCT_QUERY, variables: {slug: handle, channel: 'default-channel'}}),
    next: {
      revalidate: 300,
      tags: [`product-${handle}`, 'products'],
    },
  });

  if (!res.ok) throw new Error(`Failed to fetch product: ${res.status}`);
  const {data} = await res.json();
  return data.product;
}

Astro with on-demand rendering for cart pages

---
// src/pages/cart.astro
// Opt out of static generation for cart — render on every request
export const prerender = false;

import Layout from '../layouts/Layout.astro';
import CartPage from '../components/CartPage.tsx';
---

<Layout title="Your Cart">
  <!-- Full client hydration for interactive cart UI -->
  <CartPage client:only="react" />
</Layout>

Best Practices

• Generate static params for only your top N products — generating 100,000 product pages at build time is slow; generate the top 500 and let ISR handle the long tail on first request
• Use Next.js fetch cache tags — tag each fetch with semantic names (product-${handle}, collections) so revalidation is surgical rather than purging everything
• Separate dynamic from static concerns — product details and images should be static HTML; cart, account, and personalization should be client-rendered islands
• Pre-warm ISR pages after deployment — run a script that hits your top product URLs immediately after deploy to populate the CDN cache before customers arrive
• Use a build-time data layer — fetch all catalog data in a single large batch at build time rather than making N individual API calls for N product pages
• Set `revalidate` based on update frequency — flash sale prices need low revalidation (10s); evergreen product descriptions can be 1 hour or more
• Test with Lighthouse in CI — add a Lighthouse CI step to enforce performance budgets so regressions are caught before they reach production

Common Pitfalls

Related Skills

• @shopify-hydrogen
• @saleor-development
• @pwa-storefront
• @image-optimization-cdn
• @edge-commerce

On-Demand Cache Invalidation for a Next.js Storefront

Problem/Feature Description

SportZone runs a large statically generated Next.js storefront connected to a Saleor backend. The merchandising team runs frequent flash sales where prices drop for a few hours — they need those price changes to appear on the site within seconds of being published in the backend, not after a 5-minute ISR interval. The engineering team wants a webhook-driven approach: whenever a product or collection is updated in Saleor, the backend posts to a Next.js API endpoint, which then purges only the affected cached pages and their associated cache tags.

Security is a concern: the endpoint should not be callable by anyone on the internet without authorization. The team also uses Next.js fetch cache tags throughout the data layer, so revalidation needs to be targeted using those same tag names to avoid purging the entire cache unnecessarily.

You also need to implement the data-fetching function that assigns fetch cache tags when loading product data, so that tag-based revalidation works end-to-end.

Output Specification

Produce the following files:

• app/api/revalidate/route.ts — the Next.js API route handler for on-demand revalidation
• lib/get-product.ts — a data-fetching function that fetches a product with appropriate fetch cache tags

Do not install packages or run a build — just produce the source files.

Headless Shopify Storefront with Next.js

Problem/Feature Description

A fashion retailer, LookBook Co., is migrating away from a monolithic Shopify theme to a custom headless storefront. The marketing team wants near-perfect Core Web Vitals scores and sub-second page loads so product pages rank well in search. The engineering team has decided on Next.js with the App Router as the framework. They have a Shopify store and want product pages to be statically generated at build time, with automatic background regeneration so pricing and availability stay fresh without requiring a full redeploy.

The catalog has around 12,000 products, but only a few hundred are top sellers. Generating every single page at build time would make deploys prohibitively slow. They also need Next.js to serve product images from Shopify's CDN without errors in production.

Output Specification

Produce the following files as if scaffolding the storefront from scratch. The files should contain working TypeScript code — they don't need to be a complete running app, but they should be structurally correct and importable:

• lib/shopify.ts — the Shopify Storefront API client configuration
• app/products/[handle]/page.tsx — the product page component with static generation and ISR
• next.config.ts — Next.js configuration including CDN cache headers and image domains

All files should be placed directly in the output directory. Do not install packages or run a build — just produce the source files.

Shopping Cart State for a Static Storefront

Problem/Feature Description

HomeGoods Direct runs a statically generated Next.js product catalog with hundreds of pre-rendered product pages. Because the pages are static HTML served from a CDN, there is no server session available — the cart needs to live entirely on the client side. Users frequently navigate between pages and even close and reopen their browser while shopping; they expect items they've added to the cart to still be there when they return.

The team has decided to implement a global cart store in TypeScript. The store needs to track items added from different product pages, handle cases where a user adds the same product variant twice (it should increment the quantity rather than duplicate the entry), and persist the cart across browser sessions. The store will be consumed by a cart drawer component rendered as a client island in the layout.

Output Specification

Produce the file lib/cart-store.ts containing the complete cart store implementation in TypeScript.

The file should be self-contained and importable. Include all necessary type definitions inline. Do not install packages or run a build — just produce the source file.