Migrating from Nuxt 3 to Nuxt 4: A Practical Guide

Nuxt 4 introduces a new project structure that moves source files into an app/ directory, bringing Nuxt closer to standard Vue/Nitro conventions.

The New Directory Structure

`` app/ assets/ components/ composables/ layouts/ middleware/ pages/ plugins/ stores/ app.vue `

Key Changes

• app/ directory — All source code now lives under app/. The root pages/, components/, etc. directories are no longer auto-imported.
• compatibilityVersion: 4 — Opt-in to Nuxt 4 behavior explicitly.
• Improved TypeScript — Better type inference for composables and auto-imports.

Migration Steps

Start by setting compatibilityVersion: 4 in your nuxt.config.ts:

`ts export default defineNuxtConfig({ future: { compatibilityVersion: 4 }, }) `

Then move your source files into the app/ directory and update any path references.

Watch Out For

• Auto-imports: Components in app/components/ are still auto-imported, but nested paths may need explicit components.dirs configuration.
• Middleware: Global middleware must be in app/middleware/ with a .global.ts` suffix.
• Plugins: Explicit plugin registration is now the recommended pattern.

The migration is straightforward for most projects and the payoff is worth it — faster builds, cleaner structure, and better developer experience.