[opensourcedex]

nextjs-woocommerce is a free, open source e-commerce platforms project written in TypeScript and released under AGPL-3.0. It has 610 GitHub stars, 156 forks and 14 open issues, and was last pushed 3 hours ago. On this registry it ranks #42 of 46 tracked projects in E-commerce Platforms, with 5 head-to-head comparisons available.

What is nextjs-woocommerce?

nextjs-woocommerce is an open-source, AGPL-3.0 licensed headless e-commerce storefront built with Next.js, React and TypeScript that reads its product catalogue from a WordPress and WooCommerce backend over GraphQL and adds Algolia search, aimed at developers and agencies that already run WooCommerce and want a modern decoupled front end instead of a WordPress theme.

What it is

The project is a complete storefront application written in TypeScript on Next.js 16.1.6 and React 19.2.4. It queries product data from WooCommerce through Apollo Client against the WPGraphQL schema, renders product listings with name, price and display image, handles a cart and a checkout flow, and uses Zustand for global state. The repository counts 608 stars, 156 forks and 14 open issues, and it sits in the Business Software / E-commerce Platforms category. A live instance runs at https://next-woocommerce.dfweb.no.

The concrete problem it solves is the coupling between WooCommerce stores and WordPress theme rendering. In a default WooCommerce installation the storefront is produced by PHP templates inside WordPress, which makes the shopping experience hard to separate from the CMS and hard to modernise on its own. This project keeps WordPress and WooCommerce as the source of truth for products and orders, but replaces the theme output with a React front end that talks to the backend over GraphQL. Search is delegated to Algolia rather than to the WordPress search, so product discovery does not depend on the CMS database.

Key capabilities

  • Product listing through the WooCommerce GraphQL API, exposing name, price and display image.
  • Support for both simple products and variable products.
  • Cart and checkout with Zustand state management, persistent cart state synchronised to localStorage, selective subscriptions for efficient updates, and type-safe cart operations.
  • Cash On Delivery as the documented payment method, enabled inside WooCommerce.
  • Algolia search, which requires the wp-algolia-woo-indexer plugin to push WooCommerce products into an Algolia index.
  • Accessibility work aiming at WCAG standards where possible, with placeholder images for products that have none.
  • Form handling with React Hook Form and native HTML5 validation, animation with Framer Motion, styled-components and Animate.css, plus Playwright tests and Lighthouse CI.

Who uses it and how

  • Shops already running WooCommerce that want a decoupled, faster storefront while keeping the WordPress admin for product and order management.
  • Teams deploying to Vercel or another host, configuring environment variables from .env.example before the build.
  • Stores that need fast product discovery at catalogue scale, wiring the indexer plugin to their own Algolia account.
  • Developers who want the WordPress frontend switched off entirely, using the optional headless-wordpress plugin so only the backend stays reachable.
  • Teams working against the validated version matrix: WordPress 7.0.2, WooCommerce 10.9.4, WP GraphQL 2.18.0, WooGraphQL 1.0.3 and WPGraphQL CORS 2.1.

Getting started

Install and activate the four required WordPress plugins (WooCommerce, WPGraphQL, WPGraphQL for WooCommerce, and wp-algolia-woo-indexer), clone the repository, copy .env.example to .env and fill in the values, then start the storefront with pnpm run dev or deploy it to Vercel with the same variables.

How it compares

The facts provided name no paid product that this project replaces, and they name no comparable open-source storefront either, so on the available record it stands alone in this registry. What can be stated is that it is AGPL-3.0 licensed and self-hosted, which means there is no vendor, seat count or subscription attached to running it.

When to use it — and when not to

A self-hoster must operate WordPress with WooCommerce, the full WPGraphQL stack including the CORS plugin, the Algolia indexer plugin and an Algolia account, and keep those pieces aligned with the tested version matrix. Teams unwilling to run WordPress as a backend, or shops needing payment gateways beyond the documented Cash On Delivery method, should look elsewhere or budget integration work. The AGPL-3.0 licence is also a genuine constraint for anyone planning a closed-source derivative.

project readme (upstream, from github) — read inline

Lighthouse CI Playwright Tests Codacy Badge Quality Gate Status OWASP Security

bilde

Next.js Ecommerce site with WooCommerce backend

Live URL:

Table Of Contents (TOC)

Installation

  1. Install and activate the following required plugins, in your WordPress plugin directory:

Optional plugin:

The current release has been tested and is confirmed working with the following versions:

  • WordPress version 7.0.2
  • WooCommerce version 10.9.4
  • WP GraphQL version 2.18.0
  • WooGraphQL version 1.0.3
  • WPGraphQL CORS version 2.1

  1. For debugging and testing, install either:

    (Firefox)

    (Chrome)

  2. Make sure WooCommerce has some products already

  3. Clone or fork the repo and modify .env.example and rename it to .env

    Then set the environment variables accordingly in Vercel or your preferred hosting solution.

    See

  4. Modify the values according to your setup

  5. Start the server with pnpm run dev

  6. Enable COD (Cash On Demand) payment method in WooCommerce

  7. Add a product to the cart

  8. Proceed to checkout (Gå til kasse)

  9. Fill in your details and place the order

Features

  • Next.js version 16.1.6
  • React version 19.2.4
  • Typescript
  • Tests with Playwright
  • Connect to Woocommerce GraphQL API and list name, price and display image for products
  • Support for simple products and variable products
  • Cart handling and checkout with WooCommerce using Zustand for state management
    • Persistent cart state with localStorage sync
    • Efficient updates through selective subscriptions
    • Type-safe cart operations
    • Cash On Delivery payment method
  • Algolia search (requires algolia-woo-indexer)
  • Meets WCAG accessibility standards where possible
  • Placeholder for products without images
  • State Management:
    • Zustand for global state management
    • Apollo Client with GraphQL
  • React Hook Form
  • Native HTML5 form validation
  • Animations with Framer motion, Styled components and Animate.css
  • Loading spinner created with Styled Components
  • Shows page load progress with Nprogress during navigation
  • Fully responsive design
  • Category and product listings
  • Show stock status
  • Pretty URLs with builtin Nextjs functionality
  • Tailwind 3 for styling
  • JSDoc comments
  • Automated Lighthouse performance monitoring
    • Continuous performance, accessibility, and best practices checks
    • Automated reports on every pull request
    • Performance metrics tracking for:
      • Performance score
      • Accessibility compliance
      • Best practices adherence
      • SEO optimization
      • Progressive Web App readiness
  • Product filtering:
    • Dynamic color filtering using Tailwind's color system
    • Mobile-optimized filter layout
    • Accessible form controls with ARIA labels
    • Price range slider
    • Size and color filters
    • Product type categorization
    • Sorting options (popularity, price, newest)

Design System

This project uses a custom design system built with Tailwind CSS design tokens. The system is defined in tailwind.config.js and globals.css.

Color Palette

The palette uses a muted slate-blue primary with warm neutral surfaces — chosen to feel calm, Nordic, and appropriate for a home goods store.

Token Hex Usage
primary #3B6B8A Buttons, links, focus rings, active states
primary-light #5A8BA8 Hover accents, info states
primary-dark #254D6B Mobile nav, button hover, dark accents
accent #4A8F8F Secondary accent (teal)
surface #FAF9F7 Page background, cards, inputs (warm off-white)
surface-alt #F3F1ED Image placeholders, alternating surfaces
border #E5E2DC All borders and dividers
text #2C2C2C Primary body text (warm near-black)
text-muted #6B6862 Secondary text, descriptions
text-light #9C9890 Tertiary text, strikethrough prices
success #2D8A5E Stock status, success messages
warning #C4882A Warning states
error #B83B2A Sale prices, errors, destructive actions

Typography

  • Uses Tailwind's default system font stack
  • Type scale defined from text-xs (0.75rem) to text-5xl (3rem)
  • Hierarchy rules: product card title text-xl font-bold > price text-lg, detail page h1 text-2xl md:text-3xl font-light > card title

Accessibility

  • Global focus-visible ring (2px solid primary) on all interactive elements
  • prefers-reduced-motion: reduce disables all animations and transitions
  • Form inputs display inline error messages with role="alert" and aria-invalid
  • Required fields marked with asterisks
  • Proper type (email, tel) and autocomplete attributes on checkout inputs
  • Descriptive alt text on images
  • disabled:cursor-not-allowed on buttons
  • Semantic HTML throughout (, , , )

Button Variants

Variant Appearance Use Case
primary Solid blue (bg-primary) Main CTAs — KJØP, GÅ TIL KASSE, BESTILL
secondary Solid red (bg-error) Destructive actions — Fjern
hero White on dark overlay Hero section CTA
filter Bordered, toggleable Size filter buttons
reset Light gray surface Reset filters

All buttons include hover, active:scale-[0.98], focus-visible, and disabled states with duration-200 transitions.

CSS Custom Properties

Design tokens are also available as CSS custom properties in globals.css for use outside Tailwind:

var(--color-primary)      /* #3B6B8A */
var(--color-surface)      /* #FAF9F7 */
var(--color-text)         /* #2C2C2C */
var(--color-error)        /* #B83B2A */

Lighthouse Performance Monitoring

This project uses automated Lighthouse testing through GitHub Actions to ensure high-quality web performance. On every pull request:

  • Performance, accessibility, best practices, and SEO are automatically evaluated
  • Results are posted directly to the pull request
  • Minimum score thresholds are enforced for:
    • Performance: Analyzing loading performance, interactivity, and visual stability
    • Accessibility: Ensuring WCAG compliance and inclusive design
    • Best Practices: Validating modern web development standards
    • SEO: Checking search engine optimization fundamentals
    • PWA: Assessing Progressive Web App capabilities

View the latest Lighthouse results in the GitHub Actions tab under the "Lighthouse Check" workflow.

Security

This project runs automated OWASP security scanning on every push and pull request via GitHub Actions:

Scan Tool What It Catches
🔑 Secret Detection gitleaks Hardcoded API keys, passwords, tokens, private keys
🔍 SAST Semgrep OWASP Top 10 + React/Next.js-specific vulnerabilities
📦 Dependencies Trivy Known CVEs in npm packages (CRITICAL/HIGH)

Custom Semgrep rules cover OWASP categories A01–A10 including XSS prevention, injection detection, authentication checks, SSRF protection, and security misconfiguration. View results in the GitHub Actions tab under the "OWASP Security Scan" workflow.

Troubleshooting

I am getting a cart undefined error or other GraphQL errors

Check that you are using the latest version of the wp-graphql-woocommerce plugin

The products page isn't loading

Check the attributes of the products. Right now the application requires Size and Color.

Issues

Overall the application is working as intended, but it has not been tested extensively in a production environment. More testing and debugging is required before deploying it in a production environment.

With that said, keep the following in mind:

  • Currently only simple products and variable products work without any issues. Other product types are not known to work.
  • Only Cash On Delivery (COD) is currently supported. More payment methods may be added later.

This project is tested with BrowserStack.

TODO

  • Implement UserRegistration.component.tsx in a registration page
  • Add user dashboard with order history
  • Add Cloudflare Turnstile on registration page
  • Ensure email is real on registration page
  • Add total to cart/checkout page
  • Copy billing address to shipping address
  • Hide products not in stock

Frequently asked questions

Is nextjs-woocommerce free to use?

nextjs-woocommerce is open source under the AGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does nextjs-woocommerce do?

🔥 Next.js (React) headless eCommerce site with Typescript, WordPress (WooCommerce) backend and Algolia search

What is nextjs-woocommerce written in?

nextjs-woocommerce is primarily written in TypeScript. Its source is publicly available at https://github.com/w3bdesign/nextjs-woocommerce, and it has 610 GitHub stars.