Configuration

This document covers all configuration options available when installing and configuring your WooNext storefront.

Your installation choices are saved to woonext.json in the project root. This file is automatically created after running woonext install and used by woonext reinstall to remember your preferences.

{
  "backendDomain": "mysite.com",
  "backendProtocol": "https",
  "graphqlEndpoint": "graphql",
  "siteName": "My Store",
  "siteDescription": "Premium products online",
  "productTypes": ["grouped", "subscription"],
  "authType": "withAuth",
  "jwtAuthPlugin": "wp-graphql-headless-login",
  "credentialStorageType": "cookies",
  "includeCart": true,
  "includeCheckout": true,
  "includeAccountPages": true,
  "usingI18n": false
}

The domain of your WordPress backend without protocol.

• Type: string
• Example: mysite.com, localhost:8080

The protocol used by your WordPress backend.

• Type: "http" | "https"
• Options:
  • http - For local development
  • https - For production sites

The WPGraphQL API endpoint path.

• Type: string
• Default: graphql
• Note: This is the path, not the full URL. The full endpoint is constructed as {backendProtocol}://{backendDomain}/{graphqlEndpoint}

The name of your store, used in metadata and UI.

• Type: string
• Default: My Store

A short description of your store for metadata.

• Type: string
• Default: A Fresh NEW Store!!!

How authentication is configured for your store.

• Type: "withAuth" | "withoutAuth"
• Options:
  • withAuth - Support for both guest and registered shoppers. Includes login, registration, and account pages.
  • withoutAuth - Guest shoppers only. No user accounts or authentication flows.

Which JWT authentication plugin is installed on your WordPress backend.

• Type: "wp-graphql-jwt-authentication" | "wp-graphql-headless-login"
• Only prompted when: authType === "withAuth"
• Options:
  • wp-graphql-jwt-authentication - Standard JWT authentication
  • wp-graphql-headless-login - Supports OAuth providers (Google, Facebook, etc.)

How session credentials are stored on the client.

• Type: "cookies" | "browser"
• Options:
  • cookies - Recommended. Secure, HTTP-only cookies. Works with SSR.
  • browser - localStorage/sessionStorage. Useful for specific use cases.

Additional WooCommerce product types to support beyond simple and variable products.

• Type: string[]
• Options:
  • grouped - Grouped products
  • external - External/affiliate products
  • subscription - WooCommerce Subscriptions (requires WooGraphQL Pro)
  • bundle - Product Bundles (requires WooGraphQL Pro)
  • composite - Composite Products (requires WooGraphQL Pro)

Generate cart page and cart-related components.

• Type: boolean
• When disabled: Use Session Drop-URLs to pass the session to WordPress for cart functionality.

Generate checkout flow pages and components.

• Type: boolean
• Requires: includeCart === true
• When disabled: Use Session Drop-URLs to pass the session to WordPress for checkout functionality.

Generate user account dashboard pages (orders, addresses, payment methods, subscriptions).

• Type: boolean
• Requires: authType === "withAuth"

Add next-intl internationalization with locale-prefixed routing.

• Type: boolean
• Default: false
• When enabled:
  • Wraps the app in a [locale] route segment and adds routing.ts/request.ts under @i18n, plus createNextIntlPlugin() in next.config.ts. The default locale (en) stays unprefixed via localePrefix: 'as-needed'; additional locales are prefixed (e.g. /fr/shop). API routes are not locale-prefixed.
  • Every generated UI string renders through next-intl's t(), and the English source catalog is written to messages/en.json. To add a language, drop in a messages/<locale>.json and extend locales in routing.ts.
• When disabled: UI strings are emitted as plain English; no next-intl dependency, catalog, or locale routing is added.

After installation, configure these environment variables in .env.local:

NEXT_PUBLIC_GRAPHQL_ENDPOINT=https://mysite.com/graphql

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
CASHIER_PASSWORD=your-encrypted-application-password

NONCE_KEY=your-wordpress-nonce-key
NONCE_SALT=your-wordpress-nonce-salt

These must match the values in your WordPress wp-config.php file.