Deployment

Deploy WooNuxt to Netlify, Vercel, or any static host

WooNuxt supports three output modes. Choose the one that fits your hosting and catalog size.

Output Modes

Mode	Command	Best For
Static (SSG)	`nuxt generate`	Small–medium catalogs, cheapest hosting
Server (SSR)	`nuxt build`	Large catalogs, always-fresh data
Hybrid (ISR)	`nuxt build` + ISR routes	Large catalogs with caching

Netlify

Static Generation (Recommended)

Connect your GitHub repo in the Netlify dashboard
Set Build command: npm run generate
Set Publish directory: .output/public
Add environment variables (see below)

⚠

The publish directory above is the critical fix for static hosting. Publishing dist instead of .output/public serves prerendered HTML without Nuxt's hashed /_nuxt JS/CSS bundle — the site loads a blank page or fails to hydrate. nuxt generate always builds a static output on its own; you don't need to set NITRO_PRESET=static or any other preset override. See Troubleshooting below.

Build Hook (Trigger Rebuild from WordPress)

When content changes in WooCommerce (new products, price updates), you can trigger a rebuild automatically:

In Netlify: Site settings > Build & deploy > Build hooks → create a hook
Copy the hook URL
In WordPress: Settings > WooNuxt > Build Hook → paste the URL
Click Trigger Rebuild to test

The rebuild button appears in the WooNuxt Settings admin page only when a Build Hook URL is configured.

Vercel

Import your GitHub repo in the Vercel dashboard
Framework preset: Nuxt.js (auto-detected)
Build command and output directory come from the committed vercel.json — do not override them in the dashboard:
```
{
  "buildCommand": "npm run generate",
  "outputDirectory": ".output/public"
}
```
Add environment variables

Build Hook for Vercel

In Vercel: Project > Settings > Git > Deploy Hooks → create a hook
Copy the URL and paste it into Settings > WooNuxt > Build Hook in WordPress

Required Environment Variables

Set these in your hosting provider's environment variables panel:

# Required — always
GQL_HOST=https://yourwordpress.com/graphql
NUXT_IMAGE_DOMAINS=yourwordpress.com,cdn.yourwordpress.com

# Optional — overrides WooNuxt Settings plugin values
NUXT_PUBLIC_PRODUCTS_PER_PAGE=24
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
PRIMARY_COLOR=#7F54B2

# Optional — ISR cache lifetime (SSR/hybrid mode only)
CATALOG_ISR_TTL=3600

GQL_HOST and NUXT_IMAGE_DOMAINS are required for every deployment mode.

⚠

Never commit your .env file. All secrets should be set via your hosting provider's environment variables UI.

Image Provider (Optional)

For a static (SSG) deployment, leave NUXT_IMAGE_PROVIDER unset. It defaults to none, which serves original WordPress image URLs directly — no server dependency required.

# Do NOT set this for static deployments:
# NUXT_IMAGE_PROVIDER=ipx   ← requires a running Nuxt server, breaks static hosting

# Only set this if you deliberately want CDN image optimization:
NUXT_IMAGE_PROVIDER=netlify   # on Netlify
NUXT_IMAGE_PROVIDER=vercel    # on Vercel

ipx requires a running Nuxt server and will fail on static hosting — it only causes broken images, not the missing /_nuxt bundle issue described below.

Troubleshooting

HTML loads, but `/_nuxt/.js` and `/_nuxt/.css` return 404

This means the deployed publish directory doesn't contain Nuxt's generated /_nuxt bundle — almost always because the build published dist instead of .output/public.

Fix:

Netlify build command: npm run generate
Netlify publish directory: .output/public
Vercel: confirm vercel.json still has buildCommand: "npm run generate" and outputDirectory: ".output/public" and hasn't been overridden in the dashboard.

You do not need NITRO_PRESET=static (or any other preset override) for this — nuxt generate always produces a static build on its own.

SSL for Local Development

If you need HTTPS locally (Stripe, PWA, OAuth providers):

# Install mkcert
brew install mkcert
mkcert -install

# Generate local certificate
mkcert localhost

# Run dev server with SSL
npm run dev:ssl

The dev:ssl script is pre-configured in package.json.