---
title: "From v1 to v2"
description: "Migrate from WPNuxt 1.x to 2.x"
canonical_url: "https://wpnuxt.com/migration/v1-to-v2"
---
# From v1 to v2

> Migrate from WPNuxt 1.x to 2.x

WPNuxt 2.x is a rewrite for Nuxt 4 with a simplified API.

<callout icon="i-heroicons-cpu-chip" type="tip">

**AI-Assisted Migration:** If you're using an AI assistant with the [WPNuxt MCP server](https://wpnuxt.com/ai), 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.

</callout>

## Migration Difficulty

<table>
<thead>
  <tr>
    <th>
      Scenario
    </th>
    
    <th>
      Effort
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Basic queries (Posts, Pages, Menu)
    </td>
    
    <td>
      30 min
    </td>
  </tr>
  
  <tr>
    <td>
      Custom queries + blocks
    </td>
    
    <td>
      1-2 hours
    </td>
  </tr>
  
  <tr>
    <td>
      Using removed features
    </td>
    
    <td>
      2-4 hours
    </td>
  </tr>
</tbody>
</table>

## Breaking Changes

### Nuxt 4.1+ Required

WPNuxt 2.x requires Nuxt 4.1 or later. [Upgrade Nuxt first](https://nuxt.com/docs/getting-started/upgrade).

### Package Installation

```diff
- 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:

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

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

### Configuration

```diff
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

```diff
- <div v-sanitize-html="content" />
+ <div v-sanitize-html="content" />
```

## Removed Features

These features are **not** in v2:

<table>
<thead>
  <tr>
    <th>
      Removed
    </th>
    
    <th>
      Alternative
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        useFeaturedImage()
      </code>
    </td>
    
    <td>
      Access <code>
        post.featuredImage.node
      </code>
      
       directly
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isStaging()
      </code>
    </td>
    
    <td>
      Use <code>
        process.env.NODE_ENV
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        useWPUri()
      </code>
    </td>
    
    <td>
      Use <code>
        useRoute().params
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <ContentRenderer>
      </code>
    </td>
    
    <td>
      Use <code>
        v-sanitize-html
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <StagingBanner>
      </code>
    </td>
    
    <td>
      Implement yourself if needed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        frontendUrl
      </code>
      
       config
    </td>
    
    <td>
      Add to <code>
        runtimeConfig
      </code>
      
       if needed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
      
       config
    </td>
    
    <td>
      Use environment variables
    </td>
  </tr>
</tbody>
</table>

`usePrevNextPost()` and `<WPContent>` are still available in v2.

## Migration Checklist

- [ ] Upgrade to Nuxt 4.1+
- [ ] Update `@wpnuxt/core` to `^2.0.0`
- [ ] Update `@wpnuxt/blocks` to `^2.0.0` (if used)
- [ ] Update `nuxt.config.ts` options
- [ ] Rename composables (`useWPPosts` → `usePosts`)
- [ ] Convert async variants to lazy option (`useAsync*` → `use*({}, { lazy: true })`)
- [ ] Change `v-sanitize` to `v-sanitize-html`
- [ ] Replace removed composables
- [ ] Test all pages
- [ ] Test production build

## Common Issues

### "Cannot find module '#wpnuxt'"

```bash
pnpm dev:prepare
```

### Composable not found

Check that query name matches (case-sensitive). Run `pnpm dev:prepare` after adding queries.

### Types not working

1. Run `pnpm dev:prepare`
2. Restart your IDE's TypeScript server

## Need Help?

- [GitHub Issues](https://github.com/wpnuxt/wpnuxt/issues)
- [Full Migration Reference](https://github.com/wpnuxt/wpnuxt/blob/main/MIGRATION.md) on GitHub


## Sitemap

See the full [sitemap](https://wpnuxt.com/sitemap.md) for all pages.