What's New in v2

WPNuxt v2 is a complete rewrite built for Nuxt 4. The API is simpler, the architecture is faster, and three packages now ship from a single monorepo. This page covers all major changes.

Nuxt 4 Foundation

WPNuxt v2 requires Nuxt 4 and Node.js 20+. The entire codebase uses the Nuxt 4 directory structure (app/ for client code, server/ for server code) and benefits from Nuxt 4's improved performance and module system.

Simplified Composable API

Composable names are shorter and more intuitive. The configurable composablesPrefix is gone — every composable uses the use prefix.

- const { data } = await useWPPosts()
+ const { data } = await usePosts()

- const { data } = await useWPPageByUri({ uri })
+ const { data } = await usePageByUri({ uri })

The separate useAsync* composables are replaced by a lazy option:

- const { data } = useAsyncWPPosts()
+ const { data } = usePosts(undefined, { lazy: true })

Retry and Timeout

Composables now support automatic retry with exponential backoff and request timeouts:

const { data, retryCount, isRetrying } = await usePosts(undefined, {
  retry: 3,
  retryDelay: 1000,
  timeout: 5000
})

Multi-Layer Caching

WPNuxt v2 introduces a structured caching system with three layers that work together automatically.

Server caching is enabled by default. Configure it in nuxt.config.ts:

wpNuxt: {
  cache: {
    enabled: true,
    maxAge: 300,
    swr: true
  }
}

Per-query control gives you fine-grained options for real-time or authenticated content:

const { data } = usePosts(undefined, { clientCache: false })

See Caching for the full guide.

WPContent Component

The new <WPContent> component is the recommended way to render WordPress content. It automatically chooses the best rendering strategy and intercepts internal links for client-side navigation.

<script setup lang="ts">
const route = useRoute()
const { data: page } = await usePageByUri({ uri: route.path })
</script>

<template>
  <WPContent v-if="page" :node="page" />
</template>

When @wpnuxt/blocks is installed, <WPContent> renders structured editorBlocks via BlockRenderer. Without it, the component falls back to v-sanitize-html for safe HTML rendering. Internal WordPress links are intercepted and handled via navigateTo() for instant client-side navigation.

Serverless-Compatible Sanitization

The v-sanitize-html directive is rebuilt from the ground up. The previous implementation depended on @radya/nuxt-dompurify, which pulled in jsdom (~5.7 MB) and broke SSR on serverless platforms like Vercel.

The new built-in plugin:

• Server: passes HTML through as-is (trusted WordPress source)
• Client: lazy-loads DOMPurify with the native browser window

The directive API stays the same — no changes needed in your templates.

Gutenberg Block Rendering

The @wpnuxt/blocks package is rewritten with 10 built-in block components, automatic @nuxt/image integration, and optional Nuxt UI support.

Override any block component by creating your own in components/blocks/. The module auto-detects @nuxt/ui and uses UI components (like UButton for CoreButton) when available.

See Rendering Blocks for custom component examples.

Authentication Module

The @wpnuxt/auth package provides three authentication methods, all using secure httpOnly cookies for token storage.

The useWPAuth() composable provides a unified API across all three methods:

const { user, isAuthenticated, login, logout, refresh } = useWPAuth()

Authentication works seamlessly with SSR — cookies are included in server-side requests, so protected pages render correctly on the first load.

See Authentication for setup guides per provider.

Vercel Auto-Configuration

WPNuxt auto-detects Vercel deployments and applies the right configuration:

• Native SWR for proper ISR handling
• SSR forced for all routes (fixes catch-all route issues)
• WordPress uploads proxy (/wp-content/uploads/** forwarded to WordPress)
• @nuxt/image IPX configuration with WordPress domain alias

No manual Vercel configuration is needed.

See Deploy to Vercel for details.

Authenticated Schema Introspection

Some WordPress sites disable public GraphQL introspection. The new schemaAuthToken option lets WPNuxt download the schema with a Bearer token during builds, without exposing the token in client bundles.

wpNuxt: {
  schemaAuthToken: process.env.WPNUXT_SCHEMA_AUTH_TOKEN
}

AI-Powered Development

WPNuxt ships with a Model Context Protocol (MCP) server that enables AI assistants to interact with your WordPress site and generate WPNuxt code.

Add a single line to .mcp.json and your AI assistant can:

• Connect to your WordPress site and explore content types, menus, taxonomies, and blocks
• Generate pages, components, and custom GraphQL queries
• Help migrate from v1 to v2

{
  "mcpServers": {
    "wpnuxt": {
      "type": "sse",
      "url": "https://wpnuxt.com/mcp"
    }
  }
}

The MCP server also proxies Nuxt and Nuxt UI documentation, so you only need one MCP server configured.

See AI Tooling for the full tool reference.

Interactive Setup

Running nuxt prepare for the first time triggers an interactive setup that:

• Prompts for your WordPress URL
• Creates .env and .env.example files
• Sets up .mcp.json for AI assistant integration
• Adds .queries/ to .gitignore
• Creates the extend/queries/ folder with a README

Unified Monorepo

All three packages (@wpnuxt/core, @wpnuxt/blocks, @wpnuxt/auth) now live in a single repository. Versions are synchronized, and the packages are designed to work together seamlessly.

Developer Experience

Several improvements make day-to-day development smoother:

• Query complexity warnings — build-time analysis warns about expensive queries (deep extraction paths or many fragments)
• Build hash cache busting — every deployment gets a unique hash to ensure cache invalidation
• DevTools integration — a WPNuxt-branded tab in Nuxt DevTools for inspecting GraphQL queries
• Trailing slash handler — automatic redirect from /path to /path/ to match WordPress URI format
• GraphQL error logging — centralized error handler in development for easier debugging
• Query override warnings — notified when your custom queries override built-in ones

What's Next

WPNuxt v2 is currently in beta. The path to a stable release includes:

• End-to-end tutorials for common workflows (blog, SEO, menus)
• Media and image handling deep dive
• Troubleshooting guide with common errors and fixes
• Authentication workflow examples (SSR login states, session persistence)

Follow progress on GitHub and check the changelog for the latest updates.