Vercel
WPNuxt works out of the box on Vercel, but some configuration ensures optimal SSR and ISR behavior.
Configuration
export default defineNuxtConfig({
modules: ['@wpnuxt/core'],
wpNuxt: {
wordpressUrl: process.env.WPNUXT_WORDPRESS_URL
},
// Required for catch-all routes
routeRules: {
'/**': { ssr: true }
},
// Required for ISR
nitro: {
future: {
nativeSWR: true
}
}
})
Why These Settings?
routeRules '/**': { ssr: true }— Vercel may classify catch-all routes ([...slug].vue) as static pages. This rule forces server-side rendering for all routes, ensuring WordPress content is fetched and rendered on the server.nitro.future.nativeSWR: true— Required for Vercel's ISR (Incremental Static Regeneration) to correctly handle stale-while-revalidate. Without this, cached GraphQL responses may not revalidate properly during background updates.
Environment Variables
In Vercel dashboard, add:
| Variable | Required | Value |
|---|---|---|
WPNUXT_WORDPRESS_URL | Yes | https://your-wordpress-site.com |
WPNUXT_REVALIDATE_SECRET | No | Shared secret for cache revalidation webhook |
VERCEL_TOKEN | No | API token for CDN cache purging (create one) |
VERCEL and VERCEL_PROJECT_ID are provided automatically by Vercel at runtime.
Cache Revalidation on Vercel
On Vercel, GraphQL responses are cached at the CDN edge. WPNuxt tags all cached responses with Vercel-Cache-Tag: wpnuxt for targeted invalidation.
When WPNUXT_REVALIDATE_SECRET is set, WPNuxt registers a webhook endpoint at /api/_wpnuxt/revalidate. Adding VERCEL_TOKEN enables CDN cache invalidation via Vercel's tag-based purge API when WordPress triggers revalidation.
See Caching — Webhook Revalidation for full setup instructions including the WordPress mu-plugin.
Troubleshooting
Content not loading on navigation
Ensure both routeRules and nativeSWR are set as shown above.
SSR not executing
Check Vercel function logs for:
- Missing environment variables
- WordPress GraphQL endpoint not accessible
- CORS issues
GraphQL errors
Enable debug mode:
wpNuxt: {
debug: true
}
Check logs in Vercel dashboard → Functions → Logs.
Related Pages
- SSG — Static site generation as an alternative to SSR on Vercel
- Caching — Configure cache duration and SWR behavior
- Performance — Optimize your WPNuxt site for production