Setup & Installation

Follow this comprehensive guide to set up your Next.js WooCommerce development environment.

Prerequisites

Before you begin, ensure you have the following installed and configured:

Required Software

You should see output similar to:

Important: Make sure your WooCommerce store is accessible and the REST API is enabled before proceeding.

Step 1: Clone and Install

Start by navigating to your project directory and installing dependencies:

# Navigate to project directory
cd Your-Project-Directory

# Install all dependencies
npm install

What Gets Installed?

The installation process will install all required packages including:

• Next.js 15.5.4 – React framework
• React 19.1.0 – UI library
• @woocommerce/woocommerce-rest-api – WooCommerce API client
• Tailwind CSS 4 – Styling framework
• Other dependencies – See package.json for complete list

Step 2: Configure Environment Variables

Create a .env.local file in the root directory of your project:

# WooCommerce REST API Credentials
WOO_BASE_URL=https://your-store.com
WOO_CONSUMER_KEY=ck_your_consumer_key
WOO_CONSUMER_SECRET=cs_your_consumer_secret
WOO_VERSION=wc/v3

# Optional: Stripe (for payments)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...

Security Note: Never commit .env.local to version control. It’s already included in .gitignore.

Environment Variable Details

Step 3: Get WooCommerce API Credentials

You need to generate API keys from your WooCommerce store:

• Log in to WordPress AdminAccess your WordPress admin panel at https://your-store.com/wp-admin
• Navigate to REST API SettingsGo to WooCommerce → Settings → Advanced → REST API
• Create New API KeyClick the “Add Key” button
• Configure API Key
  • Description: Enter “Next.js Frontend” or any descriptive name
  • User: Select an admin user with proper permissions
  • Permissions: Select “Read/Write” for full access
• Generate and CopyClick “Generate API Key” and immediately copy both:
  • Consumer Key (starts with ck_)
  • Consumer Secret (starts with cs_)

  Important: The Consumer Secret is only shown once. Save it immediately!

• Add to .env.localPaste the credentials into your .env.local file

Step 4: Update WooCommerce Client

Edit src/lib/woocommerce.js to use environment variables:

import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Import WooCommerce REST API client

let wooClient = null; // Initialize WooCommerce client as null

export function getWooClient() { // Function to get WooCommerce client
  if (!wooClient) { 
    const url = process.env.WOO_BASE_URL; // Get WooCommerce base URL from environment variables
    const consumerKey = process.env.WOO_CONSUMER_KEY; // Get WooCommerce consumer key from environment variables
    const consumerSecret = process.env.WOO_CONSUMER_SECRET; // Get WooCommerce consumer secret from environment variables
    const version = process.env.WOO_VERSION || "wc/v3"; // Get WooCommerce version from environment variables

    if (!url || !consumerKey || !consumerSecret) {
      throw new Error("Missing WooCommerce environment variables");
    }

    wooClient = new WooCommerceRestApi({
      url, // Set WooCommerce base URL
      consumerKey,
      consumerSecret, // Set WooCommerce consumer secret
      version, // Set WooCommerce version
    });
  }
  return wooClient; // Return WooCommerce client
}

Note: The client uses a singleton pattern to ensure only one instance is created.

Step 5: Run Development Server

Start the Next.js development server:

npm run dev // Run development server

You should see output similar to:

▲ Next.js 15.5.4
    - Local:        http://localhost:3000
    - Ready in 2.3s

Open http://localhost:3000 in your browser to view the application.

Development Server Features

• Hot Reload – Changes reflect immediately
• Error Overlay – See errors in the browser
• Fast Refresh – Preserve component state on updates

Step 6: Build for Production

When ready to deploy, build the production version:

# Create optimized production build
npm run build

# Start production server
npm start

Production Build Process

• Optimization – Code minification and bundling
• Static Generation – Pre-renders pages where possible
• Image Optimization – Optimizes images automatically
• Performance – Best possible performance for production

Verification

To verify your setup is working correctly:

• Check that the homepage loads without errors
• Navigate to the shop page and verify products load
• Try adding a product to cart
• Check browser console for any API errors

Next Steps: Once setup is complete, check out the WooCommerce Integration guide to understand how the APIs work.

Common Setup Issues

Issue: Environment variables not loading

Solution: Restart the development server after creating/updating .env.local

Issue: API authentication errors

Solution: Verify your API credentials are correct and the API key has Read/Write permissions

Issue: CORS errors

Solution: Ensure your WooCommerce store allows requests from your development domain. Use API routes as a proxy (already configured).