You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 35bebc4
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/1.getting-started/12.upgrade.md
+63Lines changed: 63 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -97,6 +97,24 @@ Breaking or significant changes will be noted here along with migration steps fo
97
97
This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 4 using `compatibilityVersion: 4`.
98
98
::
99
99
100
+
#### Migrating Using Codemods
101
+
102
+
To facilitate the upgrade process, we have collaborated with the [Codemod](https://github.com/codemod-com/codemod) team to automate many migration steps with some open-source codemods.
103
+
104
+
::note
105
+
If you encounter any issues, please report them to the Codemod team with `npx codemod feedback` 🙏
106
+
::
107
+
108
+
For a complete list of Nuxt 4 codemods, detailed information on each, their source, and various ways to run them, visit the [Codemod Registry](https://go.codemod.com/codemod-registry).
109
+
110
+
You can run all the codemods mentioned in this guide using the following `codemod` recipe:
111
+
112
+
```bash
113
+
npx codemod@latest nuxt/4/migration-recipe
114
+
```
115
+
116
+
This command will execute all codemods in sequence, with the option to deselect any that you do not wish to run. Each codemod is also listed below alongside its respective change and can be executed independently.
117
+
100
118
#### New Directory Structure
101
119
102
120
🚦 **Impact Level**: Significant
@@ -161,6 +179,10 @@ nuxt.config.ts
161
179
1. Move your `assets/`, `components/`, `composables/`, `layouts/`, `middleware/`, `pages/`, `plugins/` and `utils/` folders under it, as well as `app.vue`, `error.vue`, `app.config.ts`. If you have an `app/router-options.ts` or `app/spa-loading-template.html`, these paths remain the same.
162
180
1. Make sure your `nuxt.config.ts`, `content/`, `layers/`, `modules/`, `public/` and `server/` folders remain outside the `app/` folder, in the root of your project.
163
181
182
+
::tip
183
+
You can automate this migration by running `npx codemod@latest nuxt/4/file-structure`
184
+
::
185
+
164
186
However, migration is _not required_. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you _already_ have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.
165
187
166
188
You can also force a v3 folder structure with the following configuration:
@@ -231,6 +253,12 @@ Previously `data` was initialized to `null` but reset in `clearNuxtData` to `und
231
253
232
254
##### Migration Steps
233
255
256
+
If you were checking if `data.value` or `error.value` were `null`, you can update these checks to check for `undefined` instead.
257
+
258
+
::tip
259
+
You can automate this step by running `npx codemod@latest nuxt/4/default-data-error-value`
260
+
::
261
+
234
262
If you encounter any issues you can revert back to the previous behavior with:
235
263
236
264
```ts twoslash [nuxt.config.ts]
@@ -288,6 +316,10 @@ The migration should be straightforward:
288
316
}
289
317
```
290
318
319
+
::tip
320
+
You can automate this step by running `npx codemod@latest nuxt/4/deprecated-dedupe-value`
321
+
::
322
+
291
323
#### Respect defaults when clearing `data` in `useAsyncData` and `useFetch`
292
324
293
325
🚦 **Impact Level**: Minimal
@@ -350,6 +382,10 @@ In most cases, no migration steps are required, but if you rely on the reactivit
350
382
})
351
383
```
352
384
385
+
::tip
386
+
If you need to, you can automate this step by running `npx codemod@latest nuxt/4/shallow-data-reactivity`
387
+
::
388
+
353
389
#### Absolute Watch Paths in `builder:watch`
354
390
355
391
🚦 **Impact Level**: Minimal
@@ -377,6 +413,29 @@ However, if you are a module author using the `builder:watch` hook and wishing t
377
413
})
378
414
```
379
415
416
+
::tip
417
+
You can automate this step by running `npx codemod@latest nuxt/4/absolute-watch-paths`
418
+
::
419
+
420
+
#### Removal of `window.__NUXT__` object
421
+
422
+
##### What Changed
423
+
424
+
We are removing the global `window.__NUXT__` object after the app finishes hydration.
425
+
426
+
##### Reasons for Change
427
+
428
+
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()`.
429
+
430
+
##### Migration Steps
431
+
432
+
The data is still available, but can be accessed with `useNuxtApp().payload`:
0 commit comments