Installation

This guide will walk you through installing WooNuxt and getting your first headless eCommerce store running.

Step 1: Clone Repository

Clone the WooNuxt repository to your local machine:

git clone https://github.com/scottyzen/woonuxt.git
cd woonuxt

Step 2: Install Dependencies

Install the required Node.js packages:

# Using npm
npm install

# Or using yarn
yarn install

# Or using pnpm
pnpm install

This will install all dependencies including Nuxt.js, Vue, and other required packages.

Step 3: Environment Configuration

Create your environment configuration file:

cp .env.example .env

Edit the .env file with your WordPress site details:

# ─── Required ────────────────────────────────────────────────
# WordPress GraphQL endpoint
GQL_HOST=https://yoursite.com/graphql

# Comma-separated list of image domains for @nuxt/image optimization
NUXT_IMAGE_DOMAINS=yoursite.com,cdn.yoursite.com

# ─── Optional ────────────────────────────────────────────────
# Origin header sent with GraphQL requests (defaults to http://localhost:3000)
APP_HOST=http://localhost:3000

# ISR cache lifetime in seconds for product/category pages (default: 3600)
# Increase for large catalogs (10 000+ products) to reduce build times
CATALOG_ISR_TTL=3600

# Override products per page set in WooNuxt Settings plugin
NUXT_PUBLIC_PRODUCTS_PER_PAGE=24

# Stripe publishable key (overrides value fetched from WordPress)
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Override brand primary color (hex, overrides WooNuxt Settings plugin value)
PRIMARY_COLOR=#7F54B2

Step 4: WordPress Setup

Before starting the frontend, you need to configure WordPress. Download and install the WooNuxt Settings Plugin which will automatically install and configure:

• WPGraphQL 2.12.0+ - GraphQL API for WordPress
• WooGraphQL 1.0.2+ - WooCommerce integration for GraphQL
• WPGraphQL Headless Login 0.4.4+ - Authentication for headless sites

Download woonuxt-settings.zip

Step 5: Start Development Server

Once WordPress is configured, start your WooNuxt development server:

# Using npm
npm run dev

# Or using yarn
yarn dev

# Or using pnpm
pnpm dev

Your store should now be running at:

http://localhost:3000

Optional: SSL for Local Development

If you need HTTPS for local development (for testing payment gateways, PWA features, or third-party integrations):

Install mkcert

# macOS (Homebrew)
brew install mkcert

# Linux
sudo apt install mkcert   # Debian/Ubuntu
sudo yum install mkcert    # Fedora/RHEL

# Using Chocolatey
choco install mkcert

# Or using Scoop
scoop install mkcert

Generate Certificate

mkcert localhost

This creates localhost.pem and localhost-key.pem files in your current directory.

Install Certificate Authority

mkcert -install

Start with SSL

# Using npm
npm run dev:ssl

# Or using yarn
yarn dev:ssl

# Or using pnpm
pnpm dev:ssl

Your store will now be available at https://localhost:3000 with a valid SSL certificate.

Verify Installation

Check that everything is working:

1. Homepage loads - Navigate to http://localhost:3000
2. Products display - Products from WooCommerce appear
3. No errors - Check browser console (F12) for errors
4. Images load - Product images display correctly
5. Navigation works - Menu and links function properly

Common Issues

GraphQL connection errors? Verify your GQL_HOST in .env matches your WordPress GraphQL endpoint and ensure the WooNuxt Settings plugin is installed.

Need help? Visit GitHub Issues for support.

Next Steps