diff --git a/docs/1.getting-started/12.upgrade.md b/docs/1.getting-started/12.upgrade.md index 4e2a34442c..9a17ebc6e6 100644 --- a/docs/1.getting-started/12.upgrade.md +++ b/docs/1.getting-started/12.upgrade.md @@ -97,6 +97,24 @@ Breaking or significant changes will be noted here along with migration steps fo 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`. :: +#### Migrating Using Codemods + +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. + +::note +If you encounter any issues, please report them to the Codemod team with `npx codemod feedback` 🙏 +:: + +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). + +You can run all the codemods mentioned in this guide using the following `codemod` recipe: + +```bash +npx codemod@latest nuxt/4/migration-recipe +``` + +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. + #### New Directory Structure 🚦 **Impact Level**: Significant @@ -161,6 +179,10 @@ nuxt.config.ts 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. 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. +::tip +You can automate this migration by running `npx codemod@latest nuxt/4/file-structure` +:: + 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. 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 ##### Migration Steps +If you were checking if `data.value` or `error.value` were `null`, you can update these checks to check for `undefined` instead. + +::tip +You can automate this step by running `npx codemod@latest nuxt/4/default-data-error-value` +:: + If you encounter any issues you can revert back to the previous behavior with: ```ts twoslash [nuxt.config.ts] @@ -288,6 +316,10 @@ The migration should be straightforward: } ``` +::tip +You can automate this step by running `npx codemod@latest nuxt/4/deprecated-dedupe-value` +:: + #### Respect defaults when clearing `data` in `useAsyncData` and `useFetch` 🚦 **Impact Level**: Minimal @@ -350,6 +382,10 @@ In most cases, no migration steps are required, but if you rely on the reactivit }) ``` +::tip +If you need to, you can automate this step by running `npx codemod@latest nuxt/4/shallow-data-reactivity` +:: + #### Absolute Watch Paths in `builder:watch` 🚦 **Impact Level**: Minimal @@ -377,6 +413,29 @@ However, if you are a module author using the `builder:watch` hook and wishing t }) ``` +::tip +You can automate this step by running `npx codemod@latest nuxt/4/absolute-watch-paths` +:: + +#### 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 @@ -465,6 +524,10 @@ const importSources = (sources: string | string[], { lazy = false } = {}) => { const importName = genSafeVariableName ``` +::tip +You can automate this step by running `npx codemod@latest nuxt/4/template-compilation-changes` +:: + #### Removal of Experimental Features 🚦 **Impact Level**: Minimal