+
```
Alternatively, you can temporarily revert to the previous behavior with:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
pendingWhenIdle: true,
},
})
```
### Key Change Behavior in `useAsyncData` and `useFetch`
🚦 **Impact Level**: Medium
#### What Changed
When using reactive keys in `useAsyncData` or `useFetch`, Nuxt automatically refetches data when the key changes. When `immediate: false` is set, `useAsyncData` will only fetch data when the key changes if the data has already been fetched once.
Previously, `useFetch` had slightly different behavior. It would always fetch data when the key changed.
Now, `useFetch` and `useAsyncData` behave consistently - by only fetch data when the key changes if the data has already been fetched once.
#### Reasons for Change
This ensures consistent behavior between `useAsyncData` and `useFetch`, and prevents unexpected fetches. If you have set `immediate: false`, then you must call `refresh` or `execute` or data will never be fetched in `useFetch` or `useAsyncData`.
#### Migration Steps
This change should generally improve the expected behavior, but if you were expecting changing the key or options of a non-immediate `useFetch`, you now will need to trigger it manually the first time.
```diff
const id = ref('123')
const { data, execute } = await useFetch('/api/test', {
query: { id },
immediate: false
)
+ watch(id, () => execute(), { once: true })
```
To opt out of this behavior:
```ts
// Or globally in your Nuxt config
export default defineNuxtConfig({
experimental: {
alwaysRunFetchOnKeyChange: true,
},
})
```
### Shallow Data Reactivity in `useAsyncData` and `useFetch`
🚦 **Impact Level**: Minimal
The `data` object returned from `useAsyncData`, `useFetch`, `useLazyAsyncData` and `useLazyFetch` is now a `shallowRef` rather than a `ref`.
#### What Changed
When new data is fetched, anything depending on `data` will still be reactive because the entire object is replaced. But if your code changes a property *within* that data structure, this will not trigger any reactivity in your app.
#### Reasons for Change
This brings a **significant** performance improvement for deeply nested objects and arrays because Vue does not need to watch every single property/array for modification. In most cases, `data` should also be immutable.
#### Migration Steps
In most cases, no migration steps are required, but if you rely on the reactivity of the data object then you have two options:
1. You can granularly opt in to deep reactivity on a per-composable basis:
```diff
- const { data } = useFetch('/api/test')
+ const { data } = useFetch('/api/test', { deep: true })
```
2. You can change the default behavior on a project-wide basis (not recommended):
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
defaults: {
useAsyncData: {
deep: true,
},
},
},
})
```
If you need to, you can automate this step by running `npx codemod@latest nuxt/4/shallow-function-reactivity`
### Absolute Watch Paths in `builder:watch`
🚦 **Impact Level**: Minimal
#### What Changed
The Nuxt `builder:watch` hook now emits a path which is absolute rather than relative to your project `srcDir`.
#### Reasons for Change
This allows us to support watching paths which are outside your `srcDir`, and offers better support for layers and other more complex patterns.
#### Migration Steps
We have already proactively migrated the public Nuxt modules which we are aware use this hook. See [issue #25339](https://github.com/nuxt/nuxt/issues/25339).
However, if you are a module author using the `builder:watch` hook and wishing to remain backwards/forwards compatible, you can use the following code to ensure that your code works the same in both Nuxt v3 and Nuxt v4:
```diff
+ import { relative, resolve } from 'node:fs'
// ...
nuxt.hook('builder:watch', async (event, path) => {
+ path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
// ...
})
```
You can automate this step by running `npx codemod@latest nuxt/4/absolute-watch-path`
### Removal of `window.__NUXT__` object
#### What Changed
We are removing the global `window.__NUXT__` object after the app finishes hydration.
#### Reasons for Change
This opens the way to multi-app patterns ([#21635](https://github.com/nuxt/nuxt/issues/21635)) and enables us to focus on a single way to access Nuxt app data - `useNuxtApp()`.
#### Migration Steps
The data is still available, but can be accessed with `useNuxtApp().payload`:
```diff
- console.log(window.__NUXT__)
+ console.log(useNuxtApp().payload)
```
### Directory index scanning
🚦 **Impact Level**: Medium
#### What Changed
Child folders in your `app/middleware/` folder are also scanned for `index` files and these are now also registered as middleware in your project.
#### Reasons for Change
Nuxt scans a number of folders automatically, including `app/middleware/` and `app/plugins/`.
Child folders in your `app/plugins/` folder are scanned for `index` files and we wanted to make this behavior consistent between scanned directories.
#### Migration Steps
Probably no migration is necessary but if you wish to revert to previous behavior you can add a hook to filter out these middleware:
```ts
export default defineNuxtConfig({
hooks: {
'app:resolve' (app) {
app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
},
},
})
```
### Template Compilation Changes
🚦 **Impact Level**: Minimal
#### What Changed
Previously, Nuxt used `lodash/template` to compile templates located on the file system using the `.ejs` file format/syntax.
In addition, we provided some template utilities (`serialize`, `importName`, `importSources`) which could be used for code-generation within these templates, which are now being removed.
#### Reasons for Change
In Nuxt v3 we moved to a 'virtual' syntax with a `getContents()` function which is much more flexible and performant.
In addition, `lodash/template` has had a succession of security issues. These do not really apply to Nuxt projects because it is being used at build-time, not runtime, and by trusted code. However, they still appear in security audits. Moreover, `lodash` is a hefty dependency and is unused by most projects.
Finally, providing code serialization functions directly within Nuxt is not ideal. Instead, we maintain projects like [unjs/knitwork](https://github.com/unjs/knitwork) which can be dependencies of your project, and where security issues can be reported/resolved directly without requiring an upgrade of Nuxt itself.
#### Migration Steps
We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:
- Moving your string interpolation logic directly into `getContents()`.
- Using a custom function to handle the replacement, such as in [https://github.com/nuxt-modules/color-mode/pull/240](https://github.com/nuxt-modules/color-mode/pull/240).
- Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of *your* project rather than Nuxt:
```diff
+ import { readFileSync } from 'node:fs'
+ import { template } from 'es-toolkit/compat'
// ...
addTemplate({
fileName: 'appinsights-vue.js'
options: { /* some options */ },
- src: resolver.resolve('./runtime/plugin.ejs'),
+ getContents({ options }) {
+ const contents = readFileSync(resolver.resolve('./runtime/plugin.ejs'), 'utf-8')
+ return template(contents)({ options })
+ },
})
```
Finally, if you are using the template utilities (`serialize`, `importName`, `importSources`), you can replace them as follows with utilities from `knitwork`:
```ts
import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'
const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"\{(.+)\}"(?=,?$)/gm, r => JSON.parse(r).replace(/^\{(.*)\}$/, '$1'))
const importSources = (sources: string | string[], { lazy = false } = {}) => {
return toArray(sources).map((src) => {
if (lazy) {
return `const ${genSafeVariableName(src)} = ${genDynamicImport(src, { comment: `webpackChunkName: ${JSON.stringify(src)}` })}`
}
return genImport(src, genSafeVariableName(src))
}).join('\n')
}
const importName = genSafeVariableName
```
You can automate this step by running `npx codemod@latest nuxt/4/template-compilation-changes`
### Default TypeScript Configuration Changes
🚦 **Impact Level**: Minimal
#### What Changed
`compilerOptions.noUncheckedIndexedAccess` is now `true` instead of `false`.
#### Reasons for Change
This change is a follow up to a prior [3.12 config update](https://github.com/nuxt/nuxt/pull/27485) where we improved our defaults, mostly adhering to [TotalTypeScript's recommendations](https://www.totaltypescript.com/tsconfig-cheat-sheet).
#### Migration Steps
There are two approaches:
1. Run a typecheck on your app and fix any new errors (recommended).
2. Override the new default in your `nuxt.config.ts`:```ts
export default defineNuxtConfig({
typescript: {
tsConfig: {
compilerOptions: {
noUncheckedIndexedAccess: false,
},
},
},
})
```
### TypeScript Configuration Splitting
🚦 **Impact Level**: Minimal
#### What Changed
Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:
1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
- `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
- `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)
- `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
- `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
- `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
3. **Opt-in project references**: New projects or those wanting better type checking can adopt TypeScript's project references feature.
4. **Context-specific type checking**: Each context now has appropriate compiler options and includes/excludes for its specific environment.
5. **New typescript.nodeTsConfig option**: You can now customize the TypeScript configuration for Node.js build-time code.
#### Reasons for Change
This change provides several benefits:
1. **Better type safety**: Each context (app, server, build-time) gets appropriate type checking with context-specific globals and APIs.
2. **Improved IDE experience**: Better IntelliSense and error reporting for different parts of your codebase.
3. **Cleaner separation**: Server code won't incorrectly suggest client-side APIs and vice versa.
4. **Performance**: TypeScript can more efficiently check code with properly scoped configurations.
For example, auto-imports are not available in your `nuxt.config.ts` (but previously this was not flagged by TypeScript). And while IDEs recognized the separate context hinted by `tsconfig.json` in your `server/` directory, this was not reflected in type-checking (requiring a separate step).
#### Migration Steps
**No migration is required** - existing projects will continue to work as before.
However, to take advantage of improved type checking, you can opt in to the new project references approach:
1. **Update your root tsconfig.json** to use project references:
If your `tsconfig.json` currently has an `"extends": "./.nuxt/tsconfig.json"` line, **remove it** before adding the references. Project references and extends are mutually exclusive.
```json
{
// Remove "extends": "./.nuxt/tsconfig.json" if present
"files": [],
"references": [
{ "path": "./.nuxt/tsconfig.app.json" },
{ "path": "./.nuxt/tsconfig.server.json" },
{ "path": "./.nuxt/tsconfig.shared.json" },
{ "path": "./.nuxt/tsconfig.node.json" }
]
}
```
2. **Remove any manual server tsconfig.json** files (like `server/tsconfig.json`) that extended `.nuxt/tsconfig.server.json`.
3. **Update your type checking scripts** to use the build flag for project references:```diff
- "typecheck": "nuxt prepare && vue-tsc --noEmit"
+ "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
```
4. **Move all type augmentations into their appropriate context**:
- If you are augmenting types for the app context, move the files to the `app/` directory.
- If you are augmenting types for the server context, move the files to the `server/` directory.
- If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.
5. **Configure TypeScript options** if needed:```ts
export default defineNuxtConfig({
typescript: {
// customize tsconfig.app.json
tsConfig: {
// ...
},
// customize tsconfig.shared.json
sharedTsConfig: {
// ...
},
// customize tsconfig.node.json
nodeTsConfig: {
// ...
},
},
nitro: {
typescript: {
// customize tsconfig.server.json
tsConfig: {
// ...
},
},
},
})
```
6. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.
The new configuration provides better type safety and IntelliSense for projects that opt in, while maintaining full backward compatibility for existing setups.
### Removal of Experimental Features
🚦 **Impact Level**: Minimal
#### What Changed
Four experimental features are no longer configurable in Nuxt 4:
- `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
- `experimental.configSchema` will be `true` (default since v3.3)
- `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
- `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
- `vite.devBundler` is no longer configurable - it will use `vite-node` by default
#### Reasons for Change
These options have been set to their current values for some time and we do not have a reason to believe that they need to remain configurable.
#### Migration Steps
- `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
- `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
### Removal of Top-Level `generate` Configuration
🚦 **Impact Level**: Minimal
#### What Changed
The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:
- `generate.exclude` - for excluding routes from prerendering
- `generate.routes` - for specifying routes to prerender
#### Reasons for Change
The top level `generate` configuration was a holdover from Nuxt 2. We've supported `nitro.prerender` for a while now, and it is the preferred way to configure prerendering in Nuxt 3+.
#### Migration Steps
Replace `generate` configuration with the corresponding `nitro.prerender` options:
```diff
export default defineNuxtConfig({
- generate: {
- exclude: ['/admin', '/private'],
- routes: ['/sitemap.xml', '/robots.txt']
- }
+ nitro: {
+ prerender: {
+ ignore: ['/admin', '/private'],
+ routes: ['/sitemap.xml', '/robots.txt']
+ }
+ }
})
```
Read more about Nitro's prerender configuration options.
### Normalized Page Component Names
🚦 **Impact Level**: Minimal
#### What Changed
When `future.compatibilityVersion` is set to `5` (or `experimental.normalizePageNames` is enabled), page component names match their route names instead of using the filename. For example, `pages/foo/index.vue` will have the component name `foo` instead of `index`.
#### Reasons for Change
Previously, Vue assigned component names based on the filename. This meant multiple pages like `pages/foo/index.vue` and `pages/bar/index.vue` would both have the component name `index`. This made `
` with `include`/`exclude` filters unreliable and required manually adding `defineOptions({ name: '...' })` to each page.
#### Migration Steps
If you rely on the current component names (e.g. in `` `include`/`exclude` lists), update them to use route names instead of filenames.
```diff
```
To disable this behavior:
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
experimental: {
normalizePageNames: false,
},
})
```
## Nuxt 2 vs. Nuxt 3+
In the table below, there is a quick comparison between 3 versions of Nuxt:
|
Feature / Version
|
Nuxt 2
|
Nuxt Bridge
|
Nuxt 3+
|
|
Vue
|
2
|
2
|
3
|
|
Stability
|
😊 Stable
|
😊 Stable
|
😊 Stable
|
|
Performance
|
🏎 Fast
|
✈️ Faster
|
🚀 Fastest
|
|
Nitro Engine
|
❌
|
✅
|
✅
|
|
ESM support
|
🌙 Partial
|
👍 Better
|
✅
|
|
TypeScript
|
☑️ Opt-in
|
🚧 Partial
|
✅
|
|
Composition API
|
❌
|
🚧 Partial
|
✅
|
|
Options API
|
✅
|
✅
|
✅
|
|
Components Auto Import
|
✅
|
✅
|
✅
|
|