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(gqlquery {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