Upgrade to Nuxt 4

[alexanderop]

🚀 Upgrade to Nuxt 4

Overview

This issue tracks the upgrade of NuxtPapier from Nuxt 3 to Nuxt 4. Nuxt 4 is currently in Release Candidate stage (as of January 2025) with the stable release expected in Q2 2025.

Motivation

• Performance improvements: Faster cold starts, Node.js compile cache, native file watching
• New directory structure: Optional app/ directory for better organization and IDE performance
• Improved data fetching: Smarter useAsyncData and useFetch with better caching
• Enhanced TypeScript support: Separate TypeScript projects for different code areas
• Better developer experience: Socket-based communication, consistent component names

Migration Steps

Phase 1: Preparation

• Upgrade to latest Nuxt 3 version (pnpm nuxt upgrade)
• Ensure all tests are passing
• Review and update dependencies
• Create a feature branch for the upgrade

Phase 2: Compatibility Testing

• Enable compatibility mode in nuxt.config.ts:

  export default defineNuxtConfig({
    future: {
      compatibilityVersion: 4
    }
  })

• Run the application and fix any immediate issues
• Run tests and ensure they pass

Phase 3: Automated Migration

• Run codemod for template compilation changes:

  npx codemod@latest nuxt/4/template-compilation-changes

• Review and validate codemod changes
• Commit changes with clear message

Phase 4: Manual Updates

• Update data fetching patterns if using deep reactivity
• Review and update any generate configuration to nitro.prerender
• Check module compatibility (especially @nuxt/content v3)
• Update TypeScript configuration if needed

Phase 5: Optional Directory Structure Migration

• Consider migrating to new app/ directory structure
• Run directory structure codemod if migrating:

  npx codemod@latest nuxt/4/file-structure

Phase 6: Testing & Validation

• Run pnpm typecheck and fix any TypeScript issues
• Run pnpm lint and fix any linting issues
• Test all routes and functionality
• Verify SEO meta tags and structured data
• Test RSS feed, sitemap, and robots.txt
• Check accessibility features (NuxtRouteAnnouncer, etc.)
• Test dark/light theme switching
• Verify blog post rendering and navigation

Phase 7: Performance Testing

• Measure build times
• Check bundle sizes
• Test cold start performance
• Verify SSG output

Resources

• Official Nuxt 4 Upgrade Guide
• Nuxt 4 Announcement
• Migration Codemods
• Complete Upgrade Guide by Mastering Nuxt

Notes

• Nuxt 3 will receive maintenance updates until end of January 2026
• No immediate rush to upgrade, but good to prepare
• Most breaking changes have configuration options to revert to old behavior

Success Criteria

• Application runs on Nuxt 4 compatibility mode without errors
• All tests pass
• No regressions in functionality
• Performance metrics are maintained or improved
• Documentation updated if needed

cc: @alexanderopalic