Nuxt 3 to Nuxt 4 Migration Guide: Complete Checklist for 2026

Nuxt 3 to Nuxt 4 Migration Guide: Complete Checklist for 2026

Last updated: February 2026 What changed in this update:

• Added migration timeline reminder (Nuxt 3 EOL: January 31, 2026)
• Updated codemod tool instructions
• Added new module compatibility matrix
• Expanded troubleshooting section

⚠️ Critical Timeline: Nuxt 3 official support ends January 31, 2026. After this date, there will be no security patches or maintenance updates. Migrating to Nuxt 4 is essential for production applications.

Why Migrate to Nuxt 4 Now?

If you're still on Nuxt 3 in early 2026, you're facing:

1. Security risks: No security patches after January 2026
2. Module incompatibility: New module versions target Nuxt 4+
3. Missing features: Performance improvements and DX enhancements
4. No LTS support: Critical for enterprise applications

The good news: Nuxt 4 is a stability-focused release with a clear upgrade path. Most projects can migrate in a few hours with the right preparation.

What's New in Nuxt 4?

Key Improvements

1. Improved App Directory Structure

• Cleaner separation of concerns
• Better TypeScript integration
• Enhanced auto-imports

2. Smarter Data Fetching

• useAsyncData and useFetch automatically share data with same keys
• Automatic cleanup on component unmount
• Reactive keys for automatic refetching
• Better caching strategies

3. Enhanced TypeScript Ergonomics

• Zero-config TypeScript setup
• Better type inference for composables
• Improved module type generation

4. Faster Development Tooling

• Optimized HMR (Hot Module Replacement)
• Faster cold starts
• Improved build performance

5. Nitro v2 Integration

• Better server-side rendering
• Enhanced API routes
• Improved edge deployment support

Pre-Migration Checklist

Before starting the migration, complete these steps:

✅ 1. Update Dependencies

Update to the latest Nuxt 3.x version first:

# Check current version
npx nuxi info

# Update to latest Nuxt 3
npm install nuxt@latest

# Or with yarn/pnpm/bun
yarn add nuxt@latest
pnpm add nuxt@latest
bun add nuxt@latest

✅ 2. Review Module Compatibility

Check if your modules support Nuxt 4:

npx nuxi upgrade --force

Compatible Modules (Nuxt 4 Ready):

• ✅ @nuxt/content (v3+)
• ✅ @nuxt/ui (v3+)
• ✅ @nuxt/icon
• ✅ @nuxtjs/seo
• ✅ @nuxtjs/tailwindcss (v6+)
• ✅ @pinia/nuxt
• ✅ @vueuse/nuxt

Modules Requiring Updates:

• ⚠️ @nuxtjs/auth → Use @sidebase/nuxt-auth or nuxt-auth-utils
• ⚠️ @nuxtjs/i18n → Update to v8+
• ⚠️ Custom server middleware → Migrate to Nitro server routes

✅ 3. Run Type Check

Fix all TypeScript errors before migrating:

npm run type-check

✅ 4. Update Test Suite

Ensure all tests pass on Nuxt 3 before migration:

npm run test

✅ 5. Backup Your Code

Create a git branch for migration:

git checkout -b migration/nuxt-4

Step-by-Step Migration Process

Step 1: Use the Codemod Tool (Recommended)

Nuxt partnered with Codemod to create an automated migration tool:

# Run the migration codemod
npx codemod@latest nuxt/4/migration-recipe

# Or with your package manager
yarn dlx codemod@latest nuxt/4/migration-recipe
pnpm dlx codemod@latest nuxt/4/migration-recipe
bun x codemod@latest nuxt/4/migration-recipe

What the codemod does:

• Updates nuxt.config.ts configuration
• Migrates directory structure (if needed)
• Updates deprecated imports
• Fixes common API changes

Step 2: Update package.json

Change Nuxt version to 4:

{
  "devDependencies": {
    "nuxt": "^4.0.0"
  }
}

Then install:

npm install

Step 3: Update nuxt.config.ts

Nuxt 3:

export default defineNuxtConfig({
  modules: ["@nuxt/content"],
  app: {
    head: {
      title: "My App",
    },
  },
})

Nuxt 4: (mostly the same, but check for deprecated options)

export default defineNuxtConfig({
  modules: ["@nuxt/content"],
  app: {
    head: {
      title: "My App",
    },
  },
  // New in Nuxt 4: Better TypeScript defaults
  typescript: {
    strict: true,
    typeCheck: true,
  },
})

Step 4: Migrate Directory Structure (Optional)

Nuxt 4 introduces an optional app/ directory structure for better organization:

Old Structure (still works):

├── components/
├── pages/
├── composables/
├── layouts/
└── plugins/

New Structure (recommended for new projects):

├── app/
│   ├── components/
│   ├── pages/
│   ├── composables/
│   ├── layouts/
│   └── plugins/
├── content/
└── public/

To adopt the new structure:

mkdir -p app
mv components app/
mv pages app/
mv composables app/
mv layouts app/
mv plugins app/

Update imports if necessary (most auto-imports work the same).

Step 5: Update Data Fetching

Nuxt 4 improves useAsyncData and useFetch:

Nuxt 3:

const { data } = await useFetch("/api/posts", {
  key: "posts",
  lazy: true,
})

Nuxt 4: (same API, better behavior)

const { data } = await useFetch("/api/posts", {
  key: "posts",
  lazy: true,
  // Now automatically shares data across components with same key
  // Automatic cleanup on unmount
})

New Features:

// Reactive keys automatically refetch
const { data } = await useFetch(`/api/posts/${postId}`)

// Multiple components with same key share data
// Component A
const { data: posts } = await useFetch("/api/posts", { key: "posts" })

// Component B (gets same data, no duplicate request)
const { data: posts } = await useFetch("/api/posts", { key: "posts" })

Step 6: Update Plugins

Nuxt 4 uses auto-imports for plugins by default:

Nuxt 3:

// plugins/my-plugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.provide("myPlugin", myPlugin)
})

Nuxt 4: (same, but better type inference)

// plugins/my-plugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.provide("myPlugin", myPlugin)
})

// Usage in components (auto-typed)
const { $myPlugin } = useNuxtApp()

Step 7: Update Server Routes

Migrate server middleware to Nitro server routes:

Old (Nuxt 3 server middleware):

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  // middleware logic
})

New (Nitro server routes - same syntax, better performance):

// server/api/auth.ts
export default defineEventHandler((event) => {
  // API route logic
  return { user: event.context.user }
})

Step 8: Replace Vuex with Pinia

If you're still using Vuex, migrate to Pinia:

Install Pinia:

npm install pinia @pinia/nuxt

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@pinia/nuxt"],
})

Migrate stores:

// stores/counter.ts
export const useCounterStore = defineStore("counter", {
  state: () => ({
    count: 0,
  }),
  actions: {
    increment() {
      this.count++
    },
  },
})

Breaking Changes & Solutions

1. Stricter TypeScript

Nuxt 4 enables stricter TypeScript by default.

Issue: Type errors that were ignored before

Solution: Fix types or adjust tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true
  }
}

2. Nested Routing Changes

Nuxt 4 has stricter nested routing behavior.

Issue: Routes not working as expected

Solution: Check file structure:

pages/
├── users/
│   ├── index.vue      → /users
│   └── [id].vue       → /users/:id

3. Module API Changes

Some modules changed their APIs.

Example - @nuxt/content v3:

// Old
const articles = await queryContent("articles").find()

// New (same API, better types)
const articles = await queryCollection("articles").find()

4. Deprecated APIs

Removed:

• @nuxt/types (use built-in types)
• nuxt.config.js (use .ts only)
• Some legacy hooks

Check deprecated APIs:

npx nuxi analyze

Common Issues & Troubleshooting

Issue 1: "Module X is not compatible with Nuxt 4"

Solution:

# Check for updates
npm outdated

# Update specific module
npm install @nuxt/content@latest

# Or find alternative
# Check Nuxt modules directory: https://nuxt.com/modules

Issue 2: TypeScript Errors After Migration

Solution:

# Regenerate types
npx nuxi prepare

# Clear cache
npx nuxi cleanup

# Check specific file
npx tsc --noEmit --pretty

Issue 3: Build Fails with "Cannot find module"

Solution:

# Clear node_modules and reinstall
rm -rf node_modules .nuxt
npm install
npx nuxi prepare

Issue 4: HMR Not Working

Solution:

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    server: {
      watch: {
        usePolling: true,
      },
    },
  },
})

Issue 5: Server Routes Not Working

Solution:

• Ensure files are in server/api/ or server/routes/
• Check Nitro configuration
• Restart dev server

Post-Migration Checklist

After completing the migration:

✅ 1. Run Full Test Suite

npm run test
npm run test:e2e

✅ 2. Type Check

npm run type-check

✅ 3. Build Production

npm run build
npm run preview

✅ 4. Performance Audit

# Run Lighthouse
npx lighthouse http://localhost:3000

✅ 5. Monitor in Production

• Set up error tracking (Sentry, LogRocket)
• Monitor Core Web Vitals
• Check analytics for issues

Migration Timeline

Recommended Schedule:

• Week 1: Pre-migration preparation (updates, backups, compatibility check)
• Week 2: Run codemod, fix breaking changes, update modules
• Week 3: Testing, performance optimization, deployment

Don't wait until January 2026! Start your migration now to avoid last-minute issues.

Performance Improvements After Migration

Real-world results from migrating to Nuxt 4:

FAQ: Nuxt 3 to Nuxt 4 Migration

When is Nuxt 3 end of life?

Nuxt 3 official support ends January 31, 2026. After this date, there will be no security patches, bug fixes, or maintenance updates.

How long does migration take?

For most projects: 4-8 hours of active work, spread over 2-3 days for testing. Large enterprise applications may take 1-2 weeks.

Is Nuxt 4 backward compatible?

Mostly yes. Nuxt 4 maintains compatibility with most Nuxt 3 APIs. The codemod tool handles most breaking changes automatically.

What if my module isn't Nuxt 4 compatible?

Check for:

1. Module updates (many released Nuxt 4 versions)
2. Alternative modules
3. Native Nuxt 4 solutions (e.g., Nitro routes instead of middleware)

Can I rollback if migration fails?

Yes. That's why we recommend creating a git branch first. You can always checkout your pre-migration code.

Should new projects start with Nuxt 4?

Absolutely. Nuxt 4 is stable, production-ready, and the recommended version for all new projects in 2026.

What about Nuxt 5?

Nuxt 5 is planned for late 2026 with Nitro v3. Nuxt 4 provides a stable foundation with a clear upgrade path to Nuxt 5.

Next Steps

Now that you've migrated to Nuxt 4:

1. Optimize Performance: Read our Nuxt 4 Performance Optimization Guide
2. Explore New Features: Check out Nuxt UI v4
3. Deploy to Edge: Learn about Edge Computing with Nuxt 4

Need Help?

Migration issues? Drop a comment below or reach out on Twitter @mubaidr.

Resources:

• Official Nuxt 4 Migration Guide
• Nuxt 4 Release Notes
• Codemod Tool
• Nuxt Discord

Ready to migrate? Start with the pre-migration checklist today, and you'll be running Nuxt 4 before the end of the week. Your future self (and your users) will thank you!