NuxtCommerce

Modern, open-source headless storefront for WooCommerce — built with Nuxt 4 & GraphQL.
Pinterest-style UI, dark mode, multi-language, and a DX focused, production-ready setup.

🚀 Live Demo

Table of Contents

• Features
• Tech Stack
• Quickstart
• Configuration
• WordPress + WooCommerce + WPGraphQL Setup
• Architecture Overview
• API Endpoints (Server)
• Internationalization (i18n)
• Performance & Caching
• Contributors & Acknowledgements
• Contact

Features

• 🎯 Headless WooCommerce store powered by WPGraphQL (+ WooGraphQL)
• ⚡️ Nuxt 4 + Nitro with server-side GraphQL proxy, SWR caching & route rules
• 🧭 Pinterest-style product grid with infinite scroll
• 🛒 Cart & Checkout (WooCommerce session cookie handled server-side)
• ❤️ Wishlist (localStorage) & Favorites page
• 🌙 Dark mode + sleek micro-interactions (skeletons, transitions)
• 🌐 Multi-language (en, nb, nl, de) via @nuxtjs/i18n
• 🖼️ Optimized images with @nuxt/image
• 🔔 Friendly toasts with Notivue
• 🔎 Good SEO defaults + JSON-LD Product schema
• ☁️ Ready for NuxtHub / Cloudflare Workers (KV cache)

Tech Stack

• Framework: Nuxt 4, Vue 3
• GraphQL Client (server): graphql-request via nuxt-graphql-request
• Styling/UI: Tailwind CSS, @nuxt/ui, Icons (Iconify)
• Images: @nuxt/image
• i18n: @nuxtjs/i18n
• Toasts: notivue
• Deployment (optional): NuxtHub + Cloudflare Workers

Project scripts live in package.json (dev, dev:ssl, build, generate, preview, deploy).

Quickstart

Requirements

• Node.js >= 18.20 (or 20.x)
• pnpm (project uses [email protected])
• A WordPress backend with WooCommerce + WPGraphQL (see setup below)

1) Clone & install

git clone https://github.com/zackha/nuxtcommerce.git
cd nuxtcommerce
pnpm install

2) Configure environment

Create .env:

GQL_HOST=https://your-woocommerce-site.com/graphql

3) Run

pnpm run dev
# optional HTTPS local dev
pnpm run dev:ssl

App runs at http://localhost:3000

4) Build / Preview

pnpm run build
pnpm run preview

Configuration

Key settings are in nuxt.config.ts:

• Runtime Config: runtimeConfig.gqlHost (reads GQL_HOST)
• Modules: @nuxt/ui, @nuxt/image, @nuxtjs/i18n, nuxt-graphql-request, notivue/nuxt, @nuxthub/core
• Route Rules: SWR caching for /categories and /favorites, prerender for /
• Nitro Prerender: /sitemap.xml, /robots.txt
• NuxtHub Cache: hub: { cache: true } (optional KV cache)

WordPress + WooCommerce + WPGraphQL Setup

This project uses WordPress + WooCommerce as the headless backend and WPGraphQL (+ WooGraphQL) as the API layer consumed by the Nuxt app. Follow the steps below carefully.

1) Fresh WordPress install (quick checklist)

1. Install WordPress on your host (or local with e.g. Local, MAMP, Docker).

2. Log in to /wp-admin.

3. Go to Settings → General and set:

   • Site Language, Timezone, Date/Time format
   • Ensure WordPress Address and Site Address use https:// in production

4. Go to Settings → Permalinks and choose Post name.

   Pretty permalinks are required for /graphql.

2) Required plugins

Install and activate:

• WooCommerce – core e-commerce
• WPGraphQL – GraphQL API for WordPress
• WPGraphQL WooCommerce (WooGraphQL) – WooCommerce schema for WPGraphQL
• (Optional) Regenerate Thumbnails – rebuild image sizes after changes

3) WooCommerce onboarding

• General: Store address, selling/shipping regions, currency (NOK/EUR/USD…)
• Products: Reviews on/off, measurements
• Tax: Enable and define rates (if applicable)
• Shipping: Create at least one zone + method (e.g., Flat rate)
• Payments: Enable Cash on Delivery (COD) for quick E2E testing
• Accounts & Privacy: Decide guest checkout
• Advanced: REST is not required; GraphQL is separate

Demo checkout posts paymentMethod: 'cod' — ensure COD is enabled for testing.

4) Product attributes & taxonomies (used in GraphQL)

Create attributes in Products → Attributes:

• Color (slug: color → taxonomy pa_color) → used via allPaColor
• Style (slug: style → taxonomy pa_style) → used via allPaStyle

Add terms (e.g., Color: Red/Blue/Black; Style: Casual/Sport).

5) Import products (CSV) or create manually

CSV Import (recommended for demo)

1. Download public/products.zip from the repo.

2. Products → Import, upload CSV(s), map columns:

   • variable for parent products
   • Attributes → pa_color, pa_style.
   • Variations CSV must reference correct parent

3. Ensure products are Published, In Stock, with prices.

Manual

• Variable product → add attributes (used for variations) → create variations from attributes → set price/stock → set images.

6) Media sizes (thumbnails & large)

Frontend queries use:

• WOOCOMMERCE_THUMBNAIL
• LARGE

Check sizes in WooCommerce (thumbnails) & Settings → Media (large). If you tweak sizes or bulk import images, run Regenerate Thumbnails.

7) Connect frontend → backend

Create .env in the Nuxt project:

GQL_HOST=https://your-woocommerce-site.com/graphql

This is read by runtimeConfig.gqlHost and used by the server utility that proxies & caches GraphQL calls.

Architecture Overview

/app
  ├─ app.vue                      # Global head/meta + header/footer + Notivue
  ├─ app.config.ts                # Site name/description, UI theme
  ├─ pages/
  │   ├─ index.vue                # Product grid, infinite scroll, filters
  │   ├─ categories.vue           # Category grid
  │   ├─ favorites.vue            # Wishlist page
  │   └─ product/[id].vue         # Product detail, gallery, variations, schema.org
  ├─ components/                  # UI building blocks (cards, carousels, cart, checkout...)
  ├─ composables/                 # useCart, useCheckout, useWishlist, useComponents
  └─ gql/                         # GraphQL queries & mutations

/server
  ├─ api/
  │   ├─ products.get.ts          # GET products (cursor pagination) — cached (SWR)
  │   ├─ product.get.ts           # GET product detail — cached (SWR)
  │   ├─ search.get.ts            # GET search (top 6) — cached (SWR)
  │   ├─ categories.get.ts        # GET categories — cached (SWR)
  │   ├─ cart/add.post.ts         # POST add to cart (Woo session cookie handling)
  │   ├─ cart/update.post.ts      # POST update quantities / remove
  │   └─ checkout.post.ts         # POST checkout (COD demo)
  ├─ routes/
  │   ├─ sitemap.xml.ts           # Minimal sitemap
  │   └─ robots.txt.ts            # Robots
  └─ utils/wpgraphql.ts           # GraphQL client + error wrapper + Woo session cookie

Flow: Client ($fetch to /api/*) → Nitro server proxies to WPGraphQL → GET endpoints are cached (SWR); POST endpoints manage the WooCommerce session cookie.

API Endpoints (Server)

• GET /api/products?search=&category=&orderby=DESC|ASC&fieldby=DATE|PRICE&after=...
• GET /api/product?slug=:slug&sku=:skuFragment
• GET /api/search?search=:q (first 6)
• GET /api/categories
• POST /api/cart/add { productId }
• POST /api/cart/update { items: [{ key, quantity }] }
• POST /api/checkout { billing: {...}, paymentMethod: 'cod' }

Internationalization (i18n)

• Locales: en-GB, nb-NO, nl-NL, de-DE
• Default: en
• Use useLocalePath() for links; SEO tags adapt per route.

Performance & Caching

• cachedEventHandler on GET handlers with SWR (stale-while-revalidate)
• Route Rules for /categories and /favorites
• Optional NuxtHub KV cache (hub: { cache: true })
• Image optimization via @nuxt/image
• Prerender: /, /sitemap.xml, /robots.txt

🙌 Contributors & Acknowledgements

We sincerely thank everyone who has contributed to NuxtCommerce. Your support, feedback, and ideas keep this project moving forward. 🚀

✨ Special thanks

Collaborator
@rikp777

_{More contributors will be highlighted here as the project grows.}

Contact

Have questions or suggestions?

• Email: [email protected]
• X (Twitter): @ZHatlen

Note
You can view the orders you create during the live demo at NuxtCommerce Admin.
From there, you can also update their statuses and add notes to your orders.