Nuxt 4 Specialist

shared/ Folder

Available in both app/ and server/. Auto-imported like composables/ and utils/.

Rules:

• No Vue-specific code (no ref, computed, onMounted)
• No Nitro-specific code (no defineEventHandler, getQuery)
• Pure isomorphic TypeScript only

shared/
  utils/format.ts       -> auto-imported everywhere
  types/index.ts        -> shared type definitions
  validators/schema.ts  -> Zod schemas usable on client and server

Use cases:

• Validation schemas (Zod) shared between forms and server routes
• Type definitions used by both client and server
• Pure utility functions (formatting, math, string manipulation)
• Constants and configuration shared across boundaries

Separate TypeScript Configs

.nuxt/tsconfig.app.json      -> app/ directory types
.nuxt/tsconfig.server.json   -> server/ directory types
.nuxt/tsconfig.shared.json   -> shared/ directory types
tsconfig.json                -> root, extends app config

This prevents server types from leaking into client code. Server-specific types (NodeJS.Process, H3Event) are only available in server/. Client-specific types (Window, Document) are only available in app/.

shallowRef for Data Fetching

Nuxt 4 uses shallowRef (not ref) for useFetch/useAsyncData data by default:

// Nuxt 3 -- deep reactive (ref)
data.value.users[0].name = 'Alice'     // triggers reactivity

// Nuxt 4 -- shallow reactive (shallowRef)
data.value.users[0].name = 'Alice'     // does NOT trigger update
data.value = { ...data.value }         // triggers update (replace top level)

// Override: opt into deep reactivity
const { data } = await useFetch('/api/users', { deep: true })

Why the Change

• Performance: Shallow reactivity avoids deep proxy wrapping of large API responses
• Predictability: Encourages immutable update patterns
• Alignment: Matches how most data fetching works (replace, not mutate)

Migration Pattern

// Before (Nuxt 3): direct mutation
data.value.items.push(newItem)

// After (Nuxt 4): immutable replacement
data.value = { ...data.value, items: [...data.value.items, newItem] }

// Or opt into deep reactivity
const { data } = await useFetch('/api/items', { deep: true })
data.value.items.push(newItem)   // works with deep: true

Global useAsyncData Key Deduplication

In Nuxt 4, multiple components using the same useAsyncData key share a single request. The second call returns cached data without re-fetching.

// Component A
const { data } = await useAsyncData('users', () => $fetch('/api/users'))

// Component B (same key = shared data, no duplicate fetch)
const { data } = await useAsyncData('users', () => $fetch('/api/users'))

Intentional: For shared state across components. Accidental: Use unique keys for unrelated data to avoid collisions.

Route Groups

Wrap directory in parentheses to group routes without affecting URL:

app/pages/
  (marketing)/
    index.vue             -> /
    pricing.vue           -> /pricing
  (app)/
    dashboard.vue         -> /dashboard
    settings.vue          -> /settings

Groups organize code logically without adding URL segments.

New APIs

useId

Generates stable unique IDs for accessibility, safe across SSR and hydration:

const id = useId()

<label :for="id">Email</label>
<input :id="id" type="email" />

useRouteAnnouncer

Announces route changes to screen readers for accessibility:

const { message, politeness } = useRouteAnnouncer()
// Automatically announces page title on navigation

Type-Safe runtimeConfig

Accessing undefined runtimeConfig keys is now a TypeScript error:

const config = useRuntimeConfig()
config.databaseUrl      // OK -- defined in nuxt.config.ts
config.undefinedKey      // TypeScript error

definePageMeta (Static Analysis)

definePageMeta is hoisted and statically analyzed at build time. Avoid dynamic values:

// BAD -- dynamic values fail static analysis
definePageMeta({
  middleware: computed(() => isAdmin ? ['admin'] : []),  // ERROR
})

// GOOD -- static values
definePageMeta({
  middleware: ['auth'],
  layout: 'admin',
})

// For dynamic behavior, use useRoute() at runtime
const route = useRoute()
const isAdmin = computed(() => route.meta.roles?.includes('admin'))

Quick Reference

What Changed from Nuxt 3

Migration Checklist

1. Set future: { compatibilityVersion: 4 } in Nuxt 3 to test changes early
2. Move app source files into app/ directory
3. Update tsconfig.json to extend .nuxt/tsconfig.app.json
4. Audit nested data mutations (shallowRef change)
5. Review all useAsyncData keys for collisions
6. Move shared isomorphic code to shared/
7. Remove dynamic values from definePageMeta
8. Update third-party modules for v4 compatibility
9. Run nuxi prepare after each step