What’s New in Nuxt 4: A Deep Dive into the Next Evolution of Nuxt.js

The release of Nuxt 4 marks a significant leap forward in the world of Vue.js and server-side rendering frameworks. With the introduction of a reimagined project structure, performance improvements, and refined developer experience, Nuxt continues to redefine modern web development. In this comprehensive guide, we’ll explore the major updates and architectural changes introduced in Nuxt 4, and why they matter for developers aiming to build faster, cleaner, and more maintainable web applications.

1. The New app/ Directory: A Unified Project Structure

One of the biggest and most exciting updates in Nuxt 4 is the introduction of the app/ directory. Previously, folders like components, composables, layouts, middleware, pages, plugins, and files such as app.vue, error.vue, and app.config.ts lived in the root directory.

In Nuxt 4, these have been moved inside the app/ directory for a more structured and intuitive layout:

app/
 ├── components/
 ├── composables/
 ├── layouts/
 ├── middleware/
 ├── pages/
 ├── plugins/
 ├── app.vue
 ├── error.vue
 └── app.config.ts

Other folders, such as public/, assets/, and server/, remain at the root level.

Why This Change?

The new structure isn’t just aesthetic—it’s built for performance, consistency, and maintainability.

1. Improved Performance:
   Nuxt now performs smarter directory scanning and optimizes file imports, reducing startup time and improving cold boot performance.

2. Enhanced Developer Experience:
   By grouping all front-end related resources under a single app/ directory, developers can easily navigate the project without confusion or duplication.

3. Future Scalability:
   The app/ directory serves as a foundation for upcoming ecosystem features like modular project extensions and hybrid rendering support.

4. Better Convention Over Configuration:
   Nuxt has always been about minimal setup. The app/ folder continues this philosophy, simplifying the mental model while keeping the framework predictable.

2. useAsyncData and useFetch Return a shallowRef

Another critical update in Nuxt 4 is the change in how data is managed in composables like useAsyncData and useFetch.

In earlier versions, both functions returned a ref, meaning that Nuxt deeply watched all changes in the returned object. Now, they return a shallowRef instead.

const { data } = useFetch('/api/user')

What Does This Mean for You?

• A shallowRef only tracks changes at the top level, not in nested properties.
• This significantly reduces unnecessary reactivity overhead, leading to better rendering performance.

When Should You Use Deep Watching?

In most cases, data fetched from APIs is static: you display it, but rarely mutate it directly. Therefore, a shallowRef is optimal.

However, if you do need reactivity (for example, when editing user data), you can enable deep reactivity like this:

const { data } = useFetch('/api/user', { deep: true })

This tells Nuxt to treat the fetched data as a full ref, ensuring that deep mutations trigger re-renders when needed.

3. Removal of window.__NUXT__

In Nuxt 3 and earlier, Nuxt injected application state into a global window.__NUXT__ object on the client side. While this approach worked, it introduced potential issues with hydration mismatches and debugging complexity.

Nuxt 4 replaces this mechanism with a cleaner and safer alternative: useNuxtApp().payload.

Accessing Payload Data in Nuxt 4

You can now retrieve the same data directly from the composable:

const payload = useNuxtApp().payload
console.log(payload.data)

Benefits of This Change

• Improved Security: Removes unnecessary exposure of global objects on the window scope.
• Consistency Between Server and Client: useNuxtApp() works seamlessly in both environments.
• Cleaner Debugging: Application payloads are now encapsulated within Nuxt’s internal context, improving code clarity and maintainability.

This change signifies a more modern and modular approach to handling application state, which is aligned with best practices in SSR frameworks.

4. Directory Index Scanning Improvements

In previous Nuxt versions, index scanning was primarily supported in specific directories like plugins/. With Nuxt 4, this behavior is extended to the middleware/ folder as well.

How It Works

When Nuxt scans the middleware/ directory, it now recursively searches for index files in subfolders and automatically registers them as middleware.

app/middleware/
 ├── auth/
 │    └── index.ts
 ├── analytics/
 │    └── index.ts
 └── logger.ts

Each of these index files will be recognized and executed by Nuxt automatically, maintaining parity with the scanning behavior in other directories like plugins/.

Why It Matters

• Consistency Across the Framework: The Nuxt team aims for uniformity in how directories are scanned, removing exceptions and confusion.
• Simplified File Organization: Developers can now group middleware logically (e.g., auth/, logger/, etc.) without worrying about manual registration.
• Improved Scalability: Makes large projects easier to maintain as the number of middleware files grows.

5. Additional Enhancements in Nuxt 4

Beyond these major updates, Nuxt 4 comes with several performance and usability improvements that solidify it as the most refined Nuxt version yet:

a. Faster Cold Starts and Dev Server Boot

The new file resolution strategy, combined with enhanced lazy-loading, reduces initial server startup time and memory footprint.

b. Improved TypeScript Support

Nuxt 4 strengthens TypeScript integration across all core modules, providing better IntelliSense, autocompletion, and error reporting.

c. Enhanced Payload Compression

Nuxt now compresses payloads more efficiently, reducing the amount of data transferred during hydration, leading to faster page transitions.

d. Better DX (Developer Experience)

From error overlays to hot module reloading and auto-imported composables, Nuxt 4 refines the developer experience for both beginners and experts.

Conclusion

Nuxt 4 isn’t just an incremental update, it’s a strategic overhaul designed for the next generation of web applications. By introducing the app/ directory, optimizing reactivity handling with shallowRef, normalizing components, and improving consistency across scanned directories, Nuxt ensures cleaner projects and better performance.

Developers can now enjoy a more predictable, performant, and future-proof framework, ready for the evolving demands of modern frontend development.