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

Problem	Solution
Build times balloon with large catalogs	Use generateStaticParams only for top products; set dynamicParams = true so the rest are rendered on demand
ISR serves stale prices during flash sales	Use revalidate = 10 for pricing data or fetch price client-side and merge into the static shell
Cart state not persisting across page navigations	Use zustand with persist middleware or a server-side cart stored in a cookie/session
Images fail to load in production	Add all commerce CDN hostnames to next.config.ts images.remotePatterns
On-demand revalidation endpoint abused	Always require a secret token in the Authorization header; rotate the token if the endpoint is publicly discoverable

Related Skills

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