|
| 1 | +--- |
| 2 | +title: Upgrading to v4 |
| 3 | +description: 'What changes for your app when you move from Nuxt DevTools v3 to v4.' |
| 4 | +--- |
| 5 | + |
| 6 | +Nuxt DevTools v4 is built on [Vite DevTools](https://github.com/vitejs/devtools). Instead of shipping its own floating panel, it registers a `Nuxt` group inside the Vite DevTools panel, next to Vue DevTools, Vite Inspect, Terminals, Messages and the other tools your Vite plugins provide. Everything you know from the Nuxt side (Pages, Components, Imports, Modules, Server Routes, Timeline, …) lives in that group. |
| 7 | + |
| 8 | +This page is for app developers. If you maintain a Nuxt module that integrates with DevTools, read the [module migration guide](/module/migration-v4) as well. |
| 9 | + |
| 10 | +## Requirements |
| 11 | + |
| 12 | +- **Vite 8.1.5 or later.** Vite DevTools only works with Vite 8. |
| 13 | +- That means **Nuxt 4.5 or later**, or **Nuxt 5**. Nuxt 4.0–4.4 ship Vite 7 and cannot run DevTools v4. |
| 14 | + |
| 15 | +If you are on an older Nuxt 4, upgrade Nuxt first. Overriding `vite` on Nuxt 4.4 to Vite 8 is not supported. |
| 16 | + |
| 17 | +## Installing |
| 18 | + |
| 19 | +### Nuxt 5 |
| 20 | + |
| 21 | +Nuxt 5 ships with DevTools v4. There is nothing to install: |
| 22 | + |
| 23 | +```ts [nuxt.config.ts] |
| 24 | +export default defineNuxtConfig({ |
| 25 | + devtools: { enabled: true }, |
| 26 | +}) |
| 27 | +``` |
| 28 | + |
| 29 | +### Nuxt 4.5+ |
| 30 | + |
| 31 | +Nuxt 4 still bundles DevTools v3. Override the bundled version with your package manager, then reinstall: |
| 32 | + |
| 33 | +::code-group |
| 34 | + |
| 35 | +```json [npm] |
| 36 | +{ |
| 37 | + "overrides": { |
| 38 | + "@nuxt/devtools": "^4.0.0" |
| 39 | + } |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +```json [yarn] |
| 44 | +{ |
| 45 | + "resolutions": { |
| 46 | + "@nuxt/devtools": "^4.0.0" |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +```json [pnpm] |
| 52 | +{ |
| 53 | + "pnpm": { |
| 54 | + "overrides": { |
| 55 | + "@nuxt/devtools": "^4.0.0" |
| 56 | + } |
| 57 | + } |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +:: |
| 62 | + |
| 63 | +Remove your lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) and run the install again so the override takes effect. |
| 64 | + |
| 65 | +## Opening DevTools |
| 66 | + |
| 67 | +The floating Nuxt button at the bottom of the page is gone; the Vite DevTools trigger takes its place. The keyboard shortcut is unchanged: :kbd{value="Shift"} + :kbd{value="Alt"} / :kbd{value="⇧ Shift"} + :kbd{value="⌥ Option"} + :kbd{value="D"} toggles the Nuxt entry. |
| 68 | + |
| 69 | +Vite DevTools can run shell commands and read files on your machine, so it asks you to **authorize the browser once per project**. On first open you will see an _Unauthorized_ badge; enter the 6-digit code printed in your terminal (or click the link printed next to it). In sandboxed environments such as StackBlitz and CodeSandbox the prompt is skipped automatically. To skip it elsewhere, set `devtools.disableAuthorization: true` in `nuxt.config.ts` — only do this on a machine you trust. |
| 70 | + |
| 71 | +To turn Vite DevTools off entirely (Nuxt DevTools included), disable it in your Vite config on Vite 8.3+: |
| 72 | + |
| 73 | +```ts [nuxt.config.ts] |
| 74 | +export default defineNuxtConfig({ |
| 75 | + vite: { |
| 76 | + devtools: false, |
| 77 | + }, |
| 78 | +}) |
| 79 | +``` |
| 80 | + |
| 81 | +## What moved |
| 82 | + |
| 83 | +| v3 | v4 | |
| 84 | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | |
| 85 | +| Floating Nuxt panel | `Nuxt` group in the Vite DevTools panel | |
| 86 | +| Nuxt Options Viewer | **Data Inspector** → `Nuxt Application` source, with a live [jora](https://discoveryjs.github.io/jora/) query workbench | |
| 87 | +| Terminals tab | Vite DevTools **Terminals** dock (shared with every tool) | |
| 88 | +| Built-in VS Code integration (`devtools.vscode`) | **Code Server** dock (`devtools.codeServer`), see below | |
| 89 | +| Vue DevTools tab | Vue DevTools dock, next to the `Nuxt` group (`vite-plugin-vue-devtools` v9) | |
| 90 | +| Popup (Picture-in-Picture) and Split Screen | Removed; Vite DevTools owns the panel layout | |
| 91 | +| `nuxi devtools enable/disable` | Removed; set `devtools.enabled` in `nuxt.config.ts` | |
| 92 | + |
| 93 | +Module tabs contributed by Nuxt modules you install (for example `@nuxt/fonts`, `@nuxt/scripts`, `nuxt-og-image`) keep working. They appear in the `Nuxt` group under the _Modules_ category. |
| 94 | + |
| 95 | +## Configuration changes |
| 96 | + |
| 97 | +### `vscode` is replaced by `codeServer` {#code-server} |
| 98 | + |
| 99 | +The VS Code integration is now the Code Server plugin. It supports a locally installed Coder [`code-server`](https://coder.com/docs/code-server/install), detected when DevTools starts and launched on demand. |
| 100 | + |
| 101 | +```diff [nuxt.config.ts] |
| 102 | +export default defineNuxtConfig({ |
| 103 | + devtools: { |
| 104 | +- vscode: { enabled: true }, |
| 105 | ++ codeServer: { enabled: true }, |
| 106 | + }, |
| 107 | +}) |
| 108 | +``` |
| 109 | + |
| 110 | +The old `vscode` value is ignored and a `NDT_DEP_0008` warning is printed. The following v3 modes no longer exist: |
| 111 | + |
| 112 | +- Microsoft `code serve-web` and `code-server serve-local` |
| 113 | +- VS Code tunnels |
| 114 | +- reusing an already running server, or starting one on boot |
| 115 | +- the `vscode-server-controller` extension |
| 116 | + |
| 117 | +The generic _open in editor_ action (from component and file links) is unaffected. `codeServer` accepts `enabled`, `bin`, `cwd`, `serverPort`, `host`, `args`, `env`, `cookieSuffix` and `startTimeout`. |
| 118 | + |
| 119 | +### Removed options |
| 120 | + |
| 121 | +- `viteDevTools` — Vite DevTools is always on; use `vite.devtools: false` to turn it off. |
| 122 | +- `ui.showPanel` and `ui.minimizePanelInactive` — the floating panel no longer exists. |
| 123 | +- `devtoolsGlobal` — DevTools cannot be installed globally any more. |
| 124 | +- `experimental.timeline` — still honored, but use `timeline.enabled` instead. |
| 125 | + |
| 126 | +### New options |
| 127 | + |
| 128 | +- `vueDevTools` (default `true`) — set to `false` to skip the Vue DevTools dock. |
| 129 | +- `dataInspector` (default `true`) — set to `false` to skip the Data Inspector source. |
| 130 | +- `disableAuthorization` (default: on in sandboxes) — skips the authorization prompt described above. |
| 131 | + |
| 132 | +## Deprecation warnings in your terminal |
| 133 | + |
| 134 | +Lines such as `[NDT_DEP_0003] extendServerRpc is deprecated` come from a Nuxt module you installed, not from your app. The module keeps working; the warning tells its author which v4 API to move to. Each code links to the relevant section of the [module migration guide](/module/migration-v4), which is the right place to point the maintainer to. |
| 135 | + |
| 136 | +## Troubleshooting |
| 137 | + |
| 138 | +- **The dev server crashes at startup mentioning `@vitejs/devtools-rolldown`.** You are on Vite 7 (Nuxt ≤ 4.4). Upgrade to Nuxt 4.5 or later. |
| 139 | +- **Opening `/__nuxt_devtools__/client/` directly shows empty data.** The client needs the connection the Vite DevTools panel gives it; open DevTools from the app page instead. |
| 140 | +- **The authorization code does not appear.** It is printed by the dev server process; look in the terminal running `nuxt dev`, not in the browser console. |
0 commit comments