Headless WooCommerce Storefront · Next.js 16

A headless e-commerce storefront that connects Next.js on the frontend to WooCommerce on the backend — delivering the performance and reliability of the world's most popular e-commerce engine.

---

Table of Contents

• What Is This?
• For Business & Product Owners
• For Digital Marketers & Analysts
• For Developers & WooCommerce Specialists
• Quick Start
• Project Structure
• Environment Variables

---

What Is This?

This is a headless WooCommerce storefront — WooCommerce runs silently in the background managing products, inventory, orders, and shipping, while Next.js powers the entire customer experience: browsing, search, cart, checkout, and order confirmation.

The result: a fast, modern shopping experience without abandoning the WooCommerce ecosystem your team already knows.

Key capabilities at a glance:

Feature	Implementation
Product catalog & search	WooCommerce Store API + ISR
Cart & checkout	Zustand + Server Actions + WC Store API
Payments	Stripe Checkout + webhook order sync
Analytics	Full GA4 Enhanced Ecommerce via GTM
Performance	React, ISR, SSG, Next/Image, Web Vitals
Testing	Jest + React Testing Library
Type safety	TypeScript + Zod

For Developers & WooCommerce Specialists

This project is a modern, headless WooCommerce storefront built with Next.js. It uses React Server Components for product and shop pages, Server Actions for all cart and checkout mutations, and Zustand for state management (cart, checkout, wishlist). All WooCommerce API credentials and Stripe keys remain server-side for security.

Key technical highlights:

• WooCommerce Store API for all product, cart, and checkout operations
• Stripe Checkout integration with webhook order status sync
• Custom nonce/session handling for guest carts
• Full GA4 Enhanced Ecommerce analytics via GTM
• Zod validation at all server boundaries
• No WordPress theme or page builder dependencies; WordPress is only the data/admin layer

Stack: Next.js, React, Zustand, Zod, Stripe, Jest, Tailwind CSS, TypeScript, WooCommerce

Required WordPress plugins: WooCommerce

Variable products: Resolved at the Next.js layer, no theme customization needed

Testing: Jest + React Testing Library

---

For Business & Product Owners

Why Headless WooCommerce?

Traditional WooCommerce stores serve every page from PHP — the database query, the HTML render, and the asset delivery all happen on the same server for every visitor. Under load, this creates bottlenecks, and performance degrades directly.

This architecture separates the concerns:

Concern	Handled by	Benefit
Product & order data	WooCommerce / WordPress	Familiar admin, existing plugins, no data migration
Page delivery	Next.js on CDN edge	Pages served in milliseconds, globally
Checkout & payments	Stripe Checkout	PCI-compliant, trusted by customers, handles 3DS
Analytics	GTM + GA4	Full funnel data, no third-party plugin needed

Performance at a Glance

• Most product pages are pre-rendered and served from the CDN — no server round-trip for the first load
• Images are automatically resized, converted to WebP/AVIF, and lazy-loaded via next/image
• Fonts are self-hosted with subsetting to eliminate layout shift (CLS = 0)
• Core Web Vitals (LCP, CLS, INP) are measured in real sessions and reported to your GA4 property automatically

Feature Set

Feature	Status
Product catalogue with filtering & sorting	✅
Full-text search	✅
Variable products (size, colour, etc.)	✅
Wishlist	✅
Slide-out cart drawer	✅
Multi-step checkout	✅
Live shipping rate calculation	✅
Stripe payment processing	✅
Cash on delivery / other WC payment methods	✅
Order confirmation page	✅
Dark / light mode	✅
Mobile-first responsive design	✅
Schema.org structured data (SEO)	✅

Scalability

The storefront is stateless — it holds no user data itself. You can run as many instances as needed behind a load balancer. WooCommerce handles inventory and order state. Stripe handles payment state. The frontend scales horizontally with zero configuration.

---

For Digital Marketers & Analysts

This storefront ships with a complete GA4 Enhanced Ecommerce implementation out of the box — most e-commerce sites miss half the funnel events or implement them incorrectly. This one does not.

Events Implemented

GA4 Event	When it fires
view_item_list	Shop/category page loads
select_item	User clicks a product card
view_item	Product detail page loads
add_to_cart	Item added to cart
remove_from_cart	Item removed from cart
add_to_wishlist	Item added to wishlist
view_cart	Cart page / cart drawer opens
begin_checkout	Checkout page loads
add_shipping_info	Shipping method selected
add_payment_info	Payment method selected
purchase	Order confirmation page loads

Every event includes the full ecommerce object: item IDs, names, categories, prices, quantities, currency, and the appropriate transaction/list context.

GTM Integration

• A single GTM container ID in .env controls all tracking — no code changes needed to swap tags or add pixels
• The dataLayer is initialized in <head> before GTM loads, so zero events are lost during the GTM bootstrap
• Adding Facebook Pixel, TikTok Pixel, or any other tag is purely a GTM configuration task — no developer involvement needed
• Server-side GTM can be configured by pointing the GTM loader script to your sGTM endpoint

Web Vitals Reporting

Every real user session reports LCP, CLS, INP, TTFB, and FCP as GTM events. This means you can segment Core Web Vitals by device, geography, or traffic source directly in GA4 or Looker Studio — no additional tooling needed.

Remarketing & Attribution

Stripe checkout sessions carry the WooCommerce order ID in metadata, and the WooCommerce order confirmation page fires the GA4 purchase event with the correct revenue, tax, and shipping values — giving your attribution models accurate data.

---

Quick Start

Prerequisites

• Node.js 20+
• pnpm 10+
• A running WordPress + WooCommerce instance (local or remote)
• Stripe account (test mode is fine)

1. Clone & install

git clone https://github.com/vakulkin/nextjs-woocommerce.git
cd nextjs-woocommerce
pnpm install

2. Configure environment variables

cp .env.example .env.local

Edit .env.local — see Environment Variables below.

3. Run in development

pnpm dev

Open http://localhost:3000.

4. Run tests

pnpm test

---

Environment Variables

# WordPress / WooCommerce
NEXT_PUBLIC_SITE_URL=https://headless-woocommerce.adsister.com
NEXT_PUBLIC_WOOCOMMERCE_PROTCOL=https
NEXT_PUBLIC_WOOCOMMERCE_HOST=headless.adsister.com
WC_CONSUMER_KEY=ck_...
WC_CONSUMER_SECRET=cs_...

# Stripe
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Analytics
NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX

---

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.