Migration
From v1 to v2
Migrate from WPNuxt 1.x to 2.x
WPNuxt 2.x is a rewrite for modern Nuxt (3.17+) with a simplified API.
AI-Assisted Migration: If you're using an AI assistant with the WPNuxt MCP server, the
wpnuxt_migrate tool can automatically scan your v1 project, identify breaking changes, detect usage anti-patterns (like composables called inside onMounted that break SSR), and generate compatibility helpers. Simply ask your AI assistant to "help me migrate to WPNuxt v2" with your project files.Migration Difficulty
| Scenario | Effort |
|---|---|
| Basic queries (Posts, Pages, Menu) | 30 min |
| Custom queries + blocks | 1-2 hours |
| Using removed features | 2-4 hours |
Breaking Changes
Nuxt 3.17+ Required
WPNuxt 2.x requires Nuxt 3.17 or later. Upgrade Nuxt first.
Package Installation
- pnpm add @wpnuxt/core@^1.0.0
+ pnpm add @wpnuxt/core@^2.0.0
Composable Names
The configurable prefix is removed. Composables now use fixed use prefix:
- const { data } = await useWPPosts()
+ const { data } = await usePosts()
- const { data } = await useAsyncWPPosts()
+ const { data } = usePosts({}, { lazy: true })
Configuration
wpNuxt: {
wordpressUrl: 'https://example.com',
- frontendUrl: 'https://frontend.com',
- defaultMenuName: 'main',
- enableCache: true,
- cacheMaxAge: 300,
- staging: false,
- logLevel: 3,
- composablesPrefix: 'useWP',
+ debug: false,
+ graphqlEndpoint: '/graphql',
+ cache: {
+ enabled: true,
+ maxAge: 300,
+ swr: true
+ },
queries: {
- extendDir: 'extend/queries',
- outputDir: '.queries'
+ extendFolder: 'extend/queries/',
+ mergedOutputFolder: '.queries/'
}
}
Directive
- <div v-sanitize-html="content" />
+ <div v-sanitize-html="content" />
Removed Features
These features are not in v2:
| Removed | Alternative |
|---|---|
useFeaturedImage() | Access post.featuredImage.node directly |
isStaging() | Use process.env.NODE_ENV |
useWPUri() | Use useRoute().params |
<ContentRenderer> | Use v-sanitize-html |
<StagingBanner> | Implement yourself if needed |
frontendUrl config | Add to runtimeConfig if needed |
staging config | Use environment variables |
usePrevNextPost() and <WPContent> are still available in v2.
Migration Checklist
- Upgrade to Nuxt 3.17+
- Update
@wpnuxt/coreto^2.0.0 - Update
@wpnuxt/blocksto^2.0.0(if used) - Update
nuxt.config.tsoptions - Rename composables (
useWPPosts→usePosts) - Convert async variants to lazy option (
useAsync*→use*({}, { lazy: true })) - Change
v-sanitizetov-sanitize-html - Replace removed composables
- Test all pages
- Test production build
Common Issues
"Cannot find module '#wpnuxt'"
pnpm dev:prepare
Composable not found
Check that query name matches (case-sensitive). Run pnpm dev:prepare after adding queries.
Types not working
- Run
pnpm dev:prepare - Restart your IDE's TypeScript server
Need Help?
- GitHub Issues
- Full Migration Reference on GitHub