Skip to content

Commit 35bebc4

Browse files
arshcodemoddanielroe
authored andcommitted
docs: codemods for migrating to Nuxt 4 (#28072)
1 parent 1843ffa commit 35bebc4

1 file changed

Lines changed: 63 additions & 0 deletions

File tree

‎docs/1.getting-started/12.upgrade.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,24 @@ Breaking or significant changes will be noted here along with migration steps fo
9797
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`.
9898
::
9999

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+
100118
#### New Directory Structure
101119

102120
🚦 **Impact Level**: Significant
@@ -161,6 +179,10 @@ nuxt.config.ts
161179
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.
162180
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.
163181

182+
::tip
183+
You can automate this migration by running `npx codemod@latest nuxt/4/file-structure`
184+
::
185+
164186
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.
165187

166188
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
231253

232254
##### Migration Steps
233255

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+
234262
If you encounter any issues you can revert back to the previous behavior with:
235263

236264
```ts twoslash [nuxt.config.ts]
@@ -288,6 +316,10 @@ The migration should be straightforward:
288316
}
289317
```
290318

319+
::tip
320+
You can automate this step by running `npx codemod@latest nuxt/4/deprecated-dedupe-value`
321+
::
322+
291323
#### Respect defaults when clearing `data` in `useAsyncData` and `useFetch`
292324

293325
🚦 **Impact Level**: Minimal
@@ -350,6 +382,10 @@ In most cases, no migration steps are required, but if you rely on the reactivit
350382
})
351383
```
352384

385+
::tip
386+
If you need to, you can automate this step by running `npx codemod@latest nuxt/4/shallow-data-reactivity`
387+
::
388+
353389
#### Absolute Watch Paths in `builder:watch`
354390

355391
🚦 **Impact Level**: Minimal
@@ -377,6 +413,29 @@ However, if you are a module author using the `builder:watch` hook and wishing t
377413
})
378414
```
379415

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`:
433+
434+
```diff
435+
- console.log(window.__NUXT__)
436+
+ console.log(useNuxtApp().payload)
437+
```
438+
380439
#### Directory index scanning
381440

382441
🚦 **Impact Level**: Medium
@@ -465,6 +524,10 @@ const importSources = (sources: string | string[], { lazy = false } = {}) => {
465524
const importName = genSafeVariableName
466525
```
467526

527+
::tip
528+
You can automate this step by running `npx codemod@latest nuxt/4/template-compilation-changes`
529+
::
530+
468531
#### Removal of Experimental Features
469532

470533
🚦 **Impact Level**: Minimal

0 commit comments

Comments
 (0)