Migrating to Nuxt 4: What Changed and Why It Matters

Why Nuxt 4?

Nuxt 4 isn't a complete rewrite — it's a refinement. The biggest change is the new app/ directory structure that separates your application code from configuration files. If you've been using Nuxt 3, the migration is straightforward but has some subtle gotchas.

The New Directory Structure

The most visible change is moving your application code into an app/ directory:

// Before (Nuxt 3)
├── components/
├── pages/
├── layouts/
├── composables/
├── plugins/

// After (Nuxt 4)
├── app/
│   ├── components/
│   ├── pages/
│   ├── layouts/
│   ├── composables/
│   └── plugins/
├── server/
├── nuxt.config.ts

Compatibility Mode

You don't have to migrate everything at once. Nuxt 4 provides a compatibility version flag in your nuxt.config.ts that lets you opt into new behaviors incrementally.

Key Changes to Watch For

• Auto-imports: The auto-import paths change with the new directory structure. Components, composables, and utilities are resolved from app/ instead of the root.
• Server directory: The server/ directory stays at the root — it's not moved into app/.
• TypeScript: The tsconfig.json paths need updating to reflect the new structure.
• Nuxt UI v3: If you're using Nuxt UI, v3 is designed for Nuxt 4 and brings Tailwind CSS v4 support.

My Migration Experience

For this portfolio site, the migration took about 2 hours. The biggest time sink was updating import paths in the server directory and ensuring the Three.js integration (via TresJS) worked correctly with the new module resolution.

Verdict

Nuxt 4 is a quality-of-life improvement that sets the stage for future innovation. The cleaner directory structure alone is worth the migration. Just make sure to test your build pipeline — some edge cases in module resolution can trip you up.