A modern, high-performance headless e-commerce storefront built with Next.js 16, React 19, and Tailwind CSS v4. Connects to WordPress/WooCommerce as a headless CMS for content and product management.

Live Demo

• Headless Architecture - Decoupled frontend with WordPress/WooCommerce backend
• Server-Side Rendering - Fast initial page loads with Next.js App Router
• Product Catalog - Browse products with categories, filters, and search
• Variable Products - Support for product variations (size, color, etc.)
• Shopping Cart - Persistent cart with localStorage
• User Authentication - JWT-based login, registration, and account management
• Checkout Flow - Complete order processing through WooCommerce
• Responsive Design - Mobile-first design that works on all devices
• Image Optimization - Automatic image optimization with Next.js Image

Before you begin, ensure you have:

• Node.js 18+ (recommended: Node.js 20)
• npm, yarn, pnpm, or bun
• WordPress site with the following plugins:
  • WooCommerce - E-commerce functionality
  • WPGraphQL - GraphQL API
  • JWT Authentication for WP REST API - User authentication

git clone https://github.com/wpacademy/nextjs-woocommerce-frontend.git
cd nextjs-woocommerce-frontend

npm install
# or
yarn install
# or
pnpm install

Copy the example environment file:

cp .env.example .env.local

Edit .env.local with your WordPress configuration:

# WordPress Configuration
NEXT_PUBLIC_WORDPRESS_URL=https://your-wordpress-site.com
NEXT_PUBLIC_GRAPHQL_URL=https://your-wordpress-site.com/graphql

# WooCommerce REST API (from WooCommerce > Settings > Advanced > REST API)
WC_CONSUMER_KEY=ck_your_consumer_key
WC_CONSUMER_SECRET=cs_your_consumer_secret

# JWT Secret (must match JWT_AUTH_SECRET_KEY in wp-config.php)
JWT_SECRET=your-jwt-secret-key

# Frontend URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

npm run dev

Open http://localhost:3000 in your browser.

1. Go to WooCommerce > Settings > Advanced > REST API
2. Click Add Key
3. Set Description (e.g., "Headless Frontend")
4. Set User to an admin user
5. Set Permissions to Read/Write
6. Click Generate API Key
7. Copy the Consumer Key and Consumer Secret to your .env.local

1. Install and activate the JWT Authentication plugin
2. Add to your wp-config.php:

define('JWT_AUTH_SECRET_KEY', 'your-unique-secret-key');
define('JWT_AUTH_CORS_ENABLE', true);

3. Add to your .htaccess (Apache) or nginx config:

RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

1. Install and activate WPGraphQL
2. Install WPGraphQL for WooCommerce (optional, for GraphQL product queries)
3. Test your GraphQL endpoint at https://your-site.com/graphql

src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   ├── account/           # User account pages
│   ├── product/[slug]/    # Product detail pages
│   ├── shop/              # Product listing
│   ├── cart/              # Shopping cart
│   ├── checkout/          # Checkout flow
│   └── layout.tsx         # Root layout
├── components/
│   ├── layout/            # Header, Footer
│   ├── product/           # Product components
│   ├── cart/              # Cart components
│   └── ui/                # Reusable UI components
├── lib/
│   ├── graphql.ts         # GraphQL client
│   ├── woocommerce.ts     # WooCommerce API client
│   ├── auth.ts            # Authentication utilities
│   └── utils.ts           # Helper functions
├── stores/                # Zustand state stores
└── types/                 # TypeScript definitions

The easiest way to deploy this Next.js app:

1. Push your code to GitHub/GitLab/Bitbucket
2. Go to vercel.com and sign in
3. Click "Add New Project"
4. Import your repository
5. Configure environment variables:
   • Add all variables from .env.local
   • Ensure NEXT_PUBLIC_SITE_URL points to your Vercel domain
6. Click Deploy

Vercel Environment Variables:

NEXT_PUBLIC_WORDPRESS_URL=https://your-wordpress-site.com
NEXT_PUBLIC_GRAPHQL_URL=https://your-wordpress-site.com/graphql
WC_CONSUMER_KEY=ck_xxxxx
WC_CONSUMER_SECRET=cs_xxxxx
JWT_SECRET=your-secret
NEXT_PUBLIC_SITE_URL=https://your-app.vercel.app

1. Push your code to GitHub/GitLab/Bitbucket
2. Go to netlify.com and sign in
3. Click "Add new site" > "Import an existing project"
4. Connect your repository
5. Configure build settings:
   • Build command: npm run build
   • Publish directory: .next
6. Add environment variables in Site settings > Environment variables
7. Install the Next.js plugin:
   • Go to Plugins > Search "Next.js" > Install @netlify/plugin-nextjs
8. Click Deploy site

Netlify Configuration (netlify.toml):

Create a netlify.toml file in your project root:

[build]
  command = "npm run build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

Netlify Environment Variables:

Add these in Site settings > Environment variables:

NEXT_PUBLIC_WORDPRESS_URL=https://your-wordpress-site.com
NEXT_PUBLIC_GRAPHQL_URL=https://your-wordpress-site.com/graphql
WC_CONSUMER_KEY=ck_xxxxx
WC_CONSUMER_SECRET=cs_xxxxx
JWT_SECRET=your-secret
NEXT_PUBLIC_SITE_URL=https://your-app.netlify.app

Build and run with Docker:

# Build the image
docker build -t headless-wp-frontend .

# Run the container
docker run -p 3000:3000 --env-file .env.local headless-wp-frontend

Or use Docker Compose:

docker-compose up

This project outputs a standalone build, making it compatible with:

• Railway - Connect repo, add env vars, deploy
• Render - Use Docker or Node.js environment
• DigitalOcean App Platform - Connect repo, configure env vars
• AWS Amplify - Import from Git, add env vars
• Google Cloud Run - Use the included Dockerfile

To allow images from your WordPress site, update next.config.ts:

images: {
  remotePatterns: [
    {
      protocol: 'https',
      hostname: 'your-wordpress-site.com',
    },
    {
      protocol: 'https',
      hostname: '*.wp.com',
    },
  ],
},

Ensure your WordPress site allows requests from your frontend domain. Add to wp-config.php:

header("Access-Control-Allow-Origin: https://your-frontend-domain.com");
header("Access-Control-Allow-Methods: GET, POST, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type, Authorization");

Or use a CORS plugin like WP CORS.

CORS Errors

• Ensure WordPress allows your frontend origin
• Check JWT plugin CORS settings
• Verify .htaccess configuration

401 Unauthorized Errors

• Verify WooCommerce API credentials
• Check that API keys have Read/Write permissions
• Ensure the user associated with API keys is an admin

GraphQL Errors

• Verify WPGraphQL plugin is active
• Test queries at your-site.com/graphql
• Check for PHP errors in WordPress

Images Not Loading

• Add your WordPress domain to next.config.ts remote patterns
• Ensure images are publicly accessible

Cart Not Persisting

• Check browser localStorage is enabled
• Clear localStorage and try again

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is open source and available under the GPL 3.0.

• Next.js - The React Framework
• WooCommerce - E-commerce for WordPress
• WPGraphQL - GraphQL API for WordPress
• Tailwind CSS - Utility-first CSS framework
• Zustand - State management