Repository navigation
docs: add the v4 upgrade guide for apps and rework the module migration guide #1108
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
644f385
fix(deps): align the Nuxt nightly with nitro 3.0.260903 so the dev se…
antfubot 6932dca
fix(devtools): keep typecheck green with the current Nuxt nightly
antfubot 08a75a5
fix(build): keep the built module when the client assets are generated
antfubot b0c9096
docs: add the v4 upgrade guide for apps and rework the module migrati…
antfubot 54a9592
chore: merge
antfu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| --- | ||
| title: Upgrading to v4 | ||
| description: 'What changes for your app when you move from Nuxt DevTools v3 to v4.' | ||
| --- | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| ## Requirements | ||
|
|
||
| - **Vite 8.1.5 or later.** Vite DevTools only works with Vite 8. | ||
| - That means **Nuxt 4.5 or later**, or **Nuxt 5**. Nuxt 4.0–4.4 ship Vite 7 and cannot run DevTools v4. | ||
|
|
||
| If you are on an older Nuxt 4, upgrade Nuxt first. Overriding `vite` on Nuxt 4.4 to Vite 8 is not supported. | ||
|
|
||
| ## Installing | ||
|
|
||
| ### Nuxt 5 | ||
|
|
||
| Nuxt 5 ships with DevTools v4. There is nothing to install: | ||
|
|
||
| ```ts [nuxt.config.ts] | ||
| export default defineNuxtConfig({ | ||
| devtools: { enabled: true }, | ||
| }) | ||
| ``` | ||
|
|
||
| ### Nuxt 4.5+ | ||
|
|
||
| Nuxt 4 still bundles DevTools v3. Override the bundled version with your package manager, then reinstall: | ||
|
|
||
| ::code-group | ||
|
|
||
| ```json [npm] | ||
| { | ||
| "overrides": { | ||
| "@nuxt/devtools": "^4.0.0" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```json [yarn] | ||
| { | ||
| "resolutions": { | ||
| "@nuxt/devtools": "^4.0.0" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```json [pnpm] | ||
| { | ||
| "pnpm": { | ||
| "overrides": { | ||
| "@nuxt/devtools": "^4.0.0" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| :: | ||
|
|
||
| Remove your lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) and run the install again so the override takes effect. | ||
|
|
||
| ## Opening DevTools | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| To turn Vite DevTools off entirely (Nuxt DevTools included), disable it in your Vite config on Vite 8.3+: | ||
|
|
||
| ```ts [nuxt.config.ts] | ||
| export default defineNuxtConfig({ | ||
| vite: { | ||
| devtools: false, | ||
| }, | ||
| }) | ||
| ``` | ||
|
|
||
| ## What moved | ||
|
|
||
| | v3 | v4 | | ||
| | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | ||
| | Floating Nuxt panel | `Nuxt` group in the Vite DevTools panel | | ||
| | Nuxt Options Viewer | **Data Inspector** → `Nuxt Application` source, with a live [jora](https://discoveryjs.github.io/jora/) query workbench | | ||
| | Terminals tab | Vite DevTools **Terminals** dock (shared with every tool) | | ||
| | Built-in VS Code integration (`devtools.vscode`) | **Code Server** dock (`devtools.codeServer`), see below | | ||
| | Vue DevTools tab | Vue DevTools dock, next to the `Nuxt` group (`vite-plugin-vue-devtools` v9) | | ||
| | Popup (Picture-in-Picture) and Split Screen | Removed; Vite DevTools owns the panel layout | | ||
| | `nuxi devtools enable/disable` | Removed; set `devtools.enabled` in `nuxt.config.ts` | | ||
|
|
||
| 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. | ||
|
|
||
| ## Configuration changes | ||
|
|
||
| ### `vscode` is replaced by `codeServer` {#code-server} | ||
|
|
||
| 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. | ||
|
|
||
| ```diff [nuxt.config.ts] | ||
| export default defineNuxtConfig({ | ||
| devtools: { | ||
| - vscode: { enabled: true }, | ||
| + codeServer: { enabled: true }, | ||
| }, | ||
| }) | ||
| ``` | ||
|
|
||
| The old `vscode` value is ignored and a `NDT_DEP_0008` warning is printed. The following v3 modes no longer exist: | ||
|
|
||
| - Microsoft `code serve-web` and `code-server serve-local` | ||
| - VS Code tunnels | ||
| - reusing an already running server, or starting one on boot | ||
| - the `vscode-server-controller` extension | ||
|
|
||
| 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`. | ||
|
|
||
| ### Removed options | ||
|
|
||
| - `viteDevTools` — Vite DevTools is always on; use `vite.devtools: false` to turn it off. | ||
| - `ui.showPanel` and `ui.minimizePanelInactive` — the floating panel no longer exists. | ||
| - `devtoolsGlobal` — DevTools cannot be installed globally any more. | ||
| - `experimental.timeline` — still honored, but use `timeline.enabled` instead. | ||
|
|
||
| ### New options | ||
|
|
||
| - `vueDevTools` (default `true`) — set to `false` to skip the Vue DevTools dock. | ||
| - `dataInspector` (default `true`) — set to `false` to skip the Data Inspector source. | ||
| - `disableAuthorization` (default: on in sandboxes) — skips the authorization prompt described above. | ||
|
|
||
| ## Deprecation warnings in your terminal | ||
|
|
||
| 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. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| - **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. | ||
| - **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. | ||
| - **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. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.