✨Next.js + WooCommerce Headless

Woo Starter Kit API

A production-ready foundation for modern commerce frontends: the client talks only to the Next.js BFF, which orchestrates WPGraphQL, WooCommerce sessions, and API security.

Unified API 🧱HttpOnly Cookies 🍪zod Validation ✅

Global Flow 🔄

  1. 1Client ➡️ src/app/api/*
  2. 2Route handler validates input and reads cookies
  3. 3Calls WPGraphQL or custom WordPress REST endpoint
  4. 4Syncs Woo session and forwards useful set-cookie
  5. 5Returns normalized success/data/error response

Complete Authentication 🔐

Login, register, refresh, logout, and password flows with server-side HttpOnly cookie handling.

Cart & Checkout 🛒

Unified cart API (get/add/remove/update/reorder) plus WooCommerce checkout URL generation.

Secure Customer Profile 👤

Address/profile updates through a secured WordPress endpoint with validation and normalization.

Robust Newsletter 📨

Double opt-in flow, abuse mitigation (honeypot, rate limit), and optional shared token to WordPress.

Available API Routes 🧭

The frontend consumes a single surface: /api/*. WordPress calls stay fully encapsulated on the server side.

Auth

  • /api/auth/login
  • /api/auth/register
  • /api/auth/me
  • /api/auth/refresh
  • /api/auth/logout

Cart

  • /api/cart/get
  • /api/cart/add
  • /api/cart/remove
  • /api/cart/update
  • /api/cart/reorder

Commerce

  • /api/checkout-url
  • /api/orders/lookup
  • /api/profile/update
  • /api/store/countries

Newsletter

  • /api/newsletter/subscribe
  • /api/newsletter/confirm

React Hooks Layer 🪝

src/hooks provides app-facing hooks that wrap API calls and SWR cache behavior for authentication and cart workflows.

useMe

src/hooks/useMe.ts

SWR hook for current user state with login/register/logout actions and cart cache refresh after auth changes.

useCart

src/hooks/useCart.ts

SWR hook for cart data with add/remove/update actions, optimistic quantity updates, and rollback on failure.

Security Included 🛡️

zod payload validation, HttpOnly cookies (authToken, refreshToken, wg_session), no-store on sensitive routes, and in-memory rate limiting on exposed endpoints.

Required WordPress Stack ⚙️

WooCommerce, WPGraphQL, WooGraphQL, WPGraphQL Headless Login, MU plugins, and custom plugins (custom-newsletter, gallery-manager).

Local Start ▶️

Configure .env.local, then run yarn install and yarn dev. The app runs at http://localhost:3000.

Custom WordPress Plugins 🔌

These custom WordPress plugins extend functionality and expose REST API endpoints for headless frontend integration.

Custom Newsletter

wordpress/custom-newsletter

Minimal WordPress plugin providing newsletter subscribe + double opt-in endpoints for the headless site.

Key Features

  • •Custom table with pending/confirmed states
  • •REST endpoints for subscribe and confirm
  • •Optional API token authentication
  • •Configurable double opt-in flow
  • •HTML email templates with placeholders
  • •Admin list with filtering, search, sorting, pagination
  • •CSV import/export and bulk actions

REST Endpoints

POST /wp-json/custom/v1/newsletter/subscribeGET /wp-json/custom/v1/newsletter/confirm

Gallery Manager

wordpress/gallery-manager

Select images from the media library and expose them through a REST API for headless galleries.

Key Features

  • •Media Library multi-select modal
  • •Selected images shown as cards (thumbnail + title)
  • •Preserve selection order for API response
  • •Optional API token authentication
  • •Full image metadata (url, srcSet, sizes, alt, caption, description)
  • •Helper functions in src/lib/gallery/api.ts

REST Endpoints

GET /wp-json/gallery-manager/v1/images