@nuxt/cli

4.0.1 · 9 Oct 2026MIT1.3M / weekRepository Homepage npm Atom feed

Latest releases

All 110 releases

4.x · latest line
4.0.1
9 Oct 2026
- dev: open BROWSER without a display server
- dev: record logs printed in the same tick as separate entries
- dev: keep log overlay rows within the terminal width
v4.0.1 is the next patch release.
Changelog
compare changes
Fixes
dev: open BROWSER without a display server
dev: record logs printed in the same tick as separate entries
dev: keep log overlay rows within the terminal width
dev: disable dev channels when BroadcastChannel throws

4.0.0

5 Oct 2026

security
Security hardening: cloudflared downloads are pinned and checksum-verified, internal dev endpoints reject unknown Host headers, GITHUB_TOKEN is only sent to GitHub, and templates can't be written outside your project (3ad862d, 14c268e, 2a1e5b0, 29e69b9).
breaking
Node.js v22.21+, v24.11+ or v26+ is now required. The CLI uses native TypeScript type stripping and Node's environment-proxy support (4360712, e4aae262). Projects on an older Node version need to upgrade before using CLI v4.
breaking
Nuxt 2 and @nuxt/bridge are no longer supported, as Nuxt 2 has been EOL for some time now (#1410).

v4.0.0 is the next major release.

Highlights

Nuxt CLI v4 is a performance, feature and DX-focused release.

It ships alongside Nuxt 4.6, and alongside resolving almost all of the open issues, we've focused on the nuxt dev experience: how quickly it starts, the information it shows you, and what happens when something goes wrong.

It's also a lot smaller. 😁

There's quite a bit to cover (more than 200 commits since v3.37), so here are just some of the things that we're particularly excited about! 🎉

Better dev-time errors with my-bad

Dev-time errors are now rendered with my-bad, which replaces youch (#1518).

A Vue error rendered by my-bad, showing the original source frame in app/pages/broken.vue

When a page fails to render, you get your own page's error state along with a small overlay in the corner. Expanding it shows the source-mapped code frame in your file, the call stack (with framework frames folded away by default), the Vue component trace, the request and environment, and the server logs that led up to the error.

The collapsed my-bad overlay in the corner of a Nuxt error page

There's a Copy error button with a few formats, including a prompt you can hand straight to an agent:

The my-bad copy menu: copy as Markdown, copy prompt for an agent, copy structured JSON

The CLI now also hosts a single live error channel, mounted at devServer.errorChannel (default /__nuxt_dev__/error). Because it lives in the CLI rather than inside Nuxt, it survives restarts of the process serving your app, and it can report errors that happen before Nuxt is up at all. So if your nuxt.config has a syntax error, or a module can't be loaded, you get a proper error page in the browser, which reloads by itself once you've fixed it:

my-bad showing a build error for a missing @nuxt/image module

Each error is rendered once, rather than at several levels (Vite plugin, Nuxt error handler, h3). The terminal gets the same treatment, with a code frame and folded dependency frames:

[request error] [GET] /broken

  ✖ TypeError (500): Cannot read properties of null (reading 'name')

    <nuxt-root> › <app> › <NuxtPage> › <RouterView> › <RouteProvider> › <broken>

      1 │ <script setup lang="ts">
      2 │ const user = { profile: null as null | { name: string } }
    › 3 │ const name = user.profile!.name.toUpperCase()
        │                            ^
      4 │ </script>

    at setup app/pages/broken.vue:3:28
    … 9 dependency frames

Watch a config syntax error recover automatically

[!NOTE]
The in-app overlay, source-mapped SSR stack traces and component traces need Nuxt 4.6 (nuxt/nuxt#36258). With an older Nuxt, the CLI still renders errors it sees itself (such as startup and config failures) with my-bad, but other errors will be rendered as before with youch.

The error channel is only served in full to loopback peers. If you expose your dev server to the network, remote peers get a scoped view without request details or error history (#1547, #1552, #1554).

An interactive terminal UI for nuxt dev

I am very excited about this one. In an interactive terminal, nuxt dev now renders a panel pinned to the bottom of the screen with your URLs, live startup progress, the current status and a row of shortcuts, while logs fold away above it (#1463).

nuxt dev with the interactive terminal UI

Everything is a single keypress away:

Key	Action
`r` / `shift-r`	Restart the dev server (optionally with a cleared cache)
`o`	Open the app in your browser
`y`	Copy the server URL to the clipboard
`i`	Versions, URLs, QR code and session info
`l` / `e`	Browse the log history, or jump to the last error
`n`	Browse served requests
`p`	Browse pages and server routes
`c`	Clear the console without deleting history
`x`	Delete log and request history
`?`	Show all shortcuts
`q`	Quit

Every request the dev server forwards is now tagged with an id, so logs and errors are attributed to the request that caused them, and you can drill into a request from the n view to see what it logged (2d9f1a8, #1557, #1558, #1474).

Select a request and press enter to open its timeline: middleware, plugins, hooks, data fetching, rendering and outgoing requests, followed by Vite compilation timings and the request's logs (#1582). The detail available depends on your Nuxt and Nitro versions. Inside a view, y copies the selected row and shift-y copies the filtered contents (#1537).

github.com/user-attachments/assets/59773f38-b39…

When something inside the dev server needs your input (for example, useScript() offering to install @nuxt/scripts), the panel steps aside and lets you answer it (#1488):

nuxt dev prompting to install a module from the interactive UI

This also adds three primitives for modules that want to play nicely with the new UI: withTerminal() to borrow the terminal, startTask() for a spinner on the status line, and notify() for a notice that lands in the log history. (To use this, make sure your module has @nuxt/kit v4.6 as a dependency...)

[!TIP]
The UI falls back to a plain stream of logs when the output isn't a terminal, in CI, when a debugger is attached, or when the terminal is too small. Pass --no-tui (or set NUXT_TUI=plain for good) if you prefer the classic output.

We've also tried to make the dev server surface more information about what it's doing:

It gives granular information about what's making a startup slow (if it is!), including the wait between "ready" and the first page (#1478, #1496), and streams the same progress to the loading page in your browser (81a5de1).
It tells you why it reloaded or restarted, and for a nuxt.config change it lists the keys that actually changed (#1402, #1403). Saves that change nothing no longer restart the server at all (#1435).
We've also done the same for nuxt build, which reports its phases and where the time went (#1490).

nuxt dev reporting which nuxt.config keys changed on restart

Faster startup, smaller install

As mentioned above, we've spent a lot of time on the size and startup time of the CLI and have cleared away a lot of unnecessary, old and deprecated dependencies.

@nuxt/cli has gone from 70 packages to 31 and from 13.1 MB to 3.5 MB installed, and the global nuxi package from 6.0 MB to 0.8 MB. We've swapped out a number of dependencies for Node built-ins or smaller alternatives (picocolors for node:util styleText, semver for verkit, fuse.js for fuzzysort, magicast for oxc, ofetch for native fetch, source-map-js for Node's SourceMap), stopped bundling jiti, and kept registry lookups and the update check off the startup path (#1379, #1409, #1413, #1416, #1425, #1430, #1443).

	v3.37.0	v4.0.0
`@nuxt/cli` install size	13.1 MB	3.5 MB	-73%
`@nuxt/cli` dependencies	70	31	-56%
`nuxi` install size	6.0 MB	0.8 MB	-87%
`nuxt --help`	108 ms	73 ms	-32%
`nuxi --help` (global)	88 ms	49 ms	-44%
`nuxt dev`: first paint	330 ms	50 ms	6.6x faster
`nuxt dev`: port bound	338 ms	104 ms	3.2x faster
`nuxt dev`: first page served	3.2 s	2.6 s	-19%
`nuxt dev`: memory at rest (Linux)	630 MB	440 MB	-30%

[!NOTE]
This was measured on a minimal pnpm create nuxt app with Nuxt 4.5.2, Node 24.15 on arm64 Linux, median of 10 runs.

A few of the changes behind this:

The dev server binds its port before your config is loaded, so the browser has something to connect to straight away, and the panel is painted before anything else happens (#1555, 88de5da, 11226da).
On Linux, we disable mimalloc's eager arena commit (used by Rolldown and oxc), which stops the dev server's memory from tracking arena size rather than live bytes (#1411).
A hard restart keeps serving on the same port using SO_REUSEPORT and hands it to the new process, rather than dropping connections while it comes back up (#1404).
We keep a single warm fork ready (configurable with NUXT_DEV_FORK_POOL_SIZE), and only start warming it once you change a file (1897968, 9a10f71).

Friendlier to agents (and to people with too many terminals)

A running dev server now records itself in a lock file in .nuxt/. That means a second nuxt dev for the same project reports the server that is already running rather than racing it for a port, and can take it over when that makes sense (#1414):

If an agent starts nuxt dev while another non-interactive server is running, it takes over (loudly).
If the running server is one you started in a terminal, a non-interactive nuxt dev refuses and tells the agent where your server is.
Pass --takeover to force it.

The lock file also powers two new commands that talk to the running server without you needing to know the port (#1417, #1432):

nuxt curl /api/hello
nuxt curl /api/users -X POST -d '{"name":"daniel"}'

nuxt task list
nuxt task run db:migrate --payload.force=true

nuxt curl pretty-printing a JSON response

nuxt curl pretty-prints and highlights responses in a terminal, and exits with 22 on HTTP errors, just like curl --fail. When nuxt dev runs non-interactively, it suggests using nuxt curl (#1464).

nuxt preview also records its running process and supports --takeover to replace an existing preview server (#1572).

nuxt info (82fe2d6), nuxt module search and nuxt task list all gain --json output (da95c8b).

nuxt docs

You can now search the Nuxt documentation from your terminal (f2dbd8c):

nuxt docs "server routes"

It searches the docs for the Nuxt version your project actually depends on, and opens the best match in your browser (or lets you pick, if there are several).

Lots of smaller things

Typos: mistype a command or a flag and we'll suggest the one you meant, and offer to rerun it (b841b87, 07e7981, 36119fe).
Layers: nuxt add can now add layers, and detects module subpaths, so nuxt add vue-sonner adds vue-sonner/nuxt (#1399).
pnpm catalogs: nuxt upgrade and nuxt info understand pnpm catalogs (#1397).
Module search shows descriptions and highlights matches (e621b9c).
nuxt module search highlighting matches
Update nudges: the CLI lets you know when a newer Nuxt release is available (#1393, #1406). Set NUXT_IGNORE_UPDATE_CHECK=1 to turn this off.
Dev server: --strictPort, --open.url for a custom path, BROWSER support, r/u/qr/copy shortcuts in plain mode, a hint about --host inside Docker or WSL, a warning when the server is reachable from the network, and StackBlitz and portless URL detection (b6ee3b9, f693d33, c1c6687, bf72c89, 29558d5, 40ab1f6, 62a030f, a0eace5).
Network failures suggest a proxy-aware retry command (#1387), and first-run failures are explained before Nuxt even loads (#1444).
Builds without a server runtime: analyze, build, dev and preview no longer assume Nitro is present, which makes the CLI more resilient to different Nitro versions and pure Vite SPA builds (#1505, #1509).
security
Security hardening: cloudflared downloads are pinned and checksum-verified, internal dev endpoints reject unknown Host headers, GITHUB_TOKEN is only sent to GitHub, and templates can't be written outside your project (3ad862d, 14c268e, 2a1e5b0, 29e69b9).

The CLI docs now live in this repository (#1465), alongside a terminal capture harness that produces the recordings you see above (#1461).

Upgrading

@nuxt/cli is a dependency of nuxt, and your project runs whichever version nuxt depends on. The way to get v4 is to upgrade to Nuxt 4.6, which depends on it:

npx nuxt upgrade --dedupe

If you'd like to try CLI v4 before upgrading Nuxt, you can override the version nuxt depends on. With pnpm, in pnpm-workspace.yaml:

overrides:
  '@nuxt/cli': ^4.0.0

With npm (or bun), in package.json:

{
  "overrides": {
    "@nuxt/cli": "^4.0.0"
  }
}

With yarn, use resolutions instead of overrides. Then reinstall, and check with npx nuxt --version.

[!NOTE]
Installing @nuxt/cli directly, or updating a global nuxi, isn't enough on its own. A global nuxi hands off to your project's own @nuxt/cli (v3.26 or later), so each project runs its own CLI version.

Breaking changes

If you're getting CLI v4 by upgrading to Nuxt 4.6, check that your Node.js version meets Nuxt 4.6's requirement (Node.js v22.21+, v24.11+ or v26+). No other migration is needed for a supported Nuxt 4 setup. 🎉

This is a major release only because it drops support for some older setups. The compatibility changes below also matter if you override @nuxt/cli on an older version of Nuxt, or use a global nuxi with older projects:

breaking
Node.js v22.21+, v24.11+ or v26+ is now required. The CLI uses native TypeScript type stripping and Node's environment-proxy support (4360712, e4aae262). Projects on an older Node version need to upgrade before using CLI v4.
breaking
Nuxt 2 and @nuxt/bridge are no longer supported, as Nuxt 2 has been EOL for some time now (#1410).
breaking
A global nuxi only hands off to a project @nuxt/cli of v3.26 or later (#1410). Every Nuxt 4 release (and Nuxt 3.18+) depends on a compatible version, so this only affects projects with an older lockfile, which will run the global nuxi's own commands instead.
breaking
nuxt init has moved out of @nuxt/cli. We consider it an edge case to use an already-installed Nuxt to create another one, so instead just use npm create nuxt@latest (or npx nuxi init). This saves around 220 KB in every Nuxt project (#1420).

There are also a couple of other changes you'll notice, though they shouldn't need any action:

breaking
nuxt dev shows the interactive UI by default in an interactive terminal. Scripts and CI are unaffected, and --no-tui or NUXT_TUI=plain restores the previous output.
breaking
Dev-time errors are rendered with my-bad instead of youch (#1518).

Changelog

compare changes

Enhancements

dev: Better errors inspired by nitro
dev: Detect portless proxy urls
dev: Add q and quit shortcuts to dev server
dev: Respect BROWSER env when opening browser
dev: Add --strictPort flag
dev: Support opening a custom path or url
dev: Add restart, url, qr and copy shortcuts
Suggest proxy-aware retry command when network fails
Nudge when a newer nuxt release is available
init: Opt yarn projects out of plug'n'play
nuxi: Defer subcommands to the project's @nuxt/cli
build: Report total build time
Support pnpm catalogs
add: Support adding layers via cli
dev: Hint about --host when bound to loopback in docker or wsl
dev: Surface the stackblitz editor url in the dev url block
dev: Report why the dev server reloaded or restarted
dev: Print changed nuxt.config keys on a config-triggered reload
Improve upgrade hints + add init hint/tip
dev: Take over a dev server already running on this project
curl,task: Add nuxt curl, nuxt task list and nuxt task run
module: Show descriptions and highlight matches while searching
curl,task: Highlight + pretty-print responses
dev: Explain first-run failures before nuxt loads
info: Add --json output
Warn on unknown options and suggest the intended one
Suggest the closest command instead of dumping help
module,task: Add --json to module search and task list
docs: Add nuxt docs command
Offer to rerun with correct spelling of commands/args
dev: Stream live startup progress to the loading page and terminal
dev: Suggest using nuxt curl when running non-interactively
dev: Interactive terminal ui for the dev server
dev: Narrate what a slow startup is waiting on
dev: Warn when the dev server is reachable from the network
dev: A terminal host for prompts, tasks and notifications
build: Report build phases and where the time went
dev: Narrate the wait between ready and the first page
analyze,build,dev,preview: Support builds without a server runtime
dev: Render dev-time errors with my-bad
dev: Tag every forwarded request with its id
dev: Copy everything a view shows with shift-y
dev: Trace requests on a timeline in the network view
preview: Track and allow taking over another preview process

Performance

dev: Warm the fork pool on first file change instead of on ready
dev: Warm a single fork by default, overridable with NUXT_DEV_FORK_POOL_SIZE
nuxi: Do not bundle jiti
nuxi: ⚠️ Defer to project cli + drop nuxt <3.26 support
Disable mimalloc eager arena commit at cli entry
Keep youch, the registry and the update check off startup
Replace picocolors with node:util styleText
info,upgrade: Use confbox rather than pnpm-workspace-yaml
dev: Use builtin node SourceMap instead of source-map-js
dev: Use node createHash for hashing build manifest
dev,module: Handle registry trailing slashes internally
module: Swap fzf for fuzzysort
dev: Stop saves that change nothing from restarting the dev server
Keep engine and update checks off the version path
dev: Bind the dev server port before the config is loaded
Drop unneeded node imports on fast path
dev: Improve time to first paint
dev: Paint the panel for nuxi dev before handing to project cli
upgrade: Resolve package manager version asynchronously
Only load node:http when a proxy is configured
dev: Keep update check + confbox parsers off the panel startup path
Load catalog, registry and docs index lazily

Fixes

dev: Hide timestamp and remove outdated filters
dev: Pin cloudflared version and shut tunnels down gracefully
init: Make dependency install recoverable and package-manager aware
dev: Ignore link-local addresses in network urls
dev: Do not report or restart on broken pipes
dev: Warn when a browser cannot be opened and caption qr codes
Remove duplicate, prefer 'nuxt' + add help snapshots
_dev,start: Hide _dev and start commands from help output
typecheck: Only imply --build for solution-style tsconfigs
dev: Open inspector only in the process serving the app
upgrade: Find lockfile in nearest directory, not workspace root
dev: Settle in-flight responses when nuxt reloads
preview: Declare serve as an optional peer dependency
upgrade: Take ownership of dependency installation
dev: Strip windows working directory from rendered errors
init: Print cd step for single-character project directories
Match exsolve resolution errors when @nuxt/kit is missing
dev: Take us out of raw mode after clack finishes
Stop forcing --no-clear on programmatic commands
dev: Unpause stdin when using clack spinners on windows
Don't mistake another package.json for nuxt's own
paths: Emit clickable hyperlinks for printed paths
analyze: Skip prerendering routes when building
dev: Bind directly with --strictPort and translate bind errors
dev: Reap every pooled fork on shutdown
dev: Track cold forks in the pool so shutdown reaps them
dev: Keep warming the pool once the app is served by a fork
dev: Warn on invalid --host and explain failed binds
dev: Omit default ports and decode urls in the dev url block
dev: Drain connections before force-closing the dev server
dev: Keep serving during a hard restart using SO_REUSEPORT
dev: Handle a rejected reusePort option and a failed cold restart
Resolve npm auth token from parseINI result
dev: Do not end the dev session when a replaced fork exits non-zero
dev: Trace youch into dist so its assets ship with the build
Do not read the project manifest when a dependency is missing
dev: Do not restart when a client aborts a connection
Correctly report Vite version when using Vite+
dev: Fall back to the project's loading template
init: ⚠️ Drop init command from @nuxt/cli
dev: Show loading screen in initial startup
dev: Restore isolated environment host defaults
dev: Await close hooks on shutdown + warn on hanging processes
cli: Preserve local command failures
cli: Align Node warning with package engines
add-template: Expose template options
analyze: Guard builds and simplify serving
cleanup: Make directory removal safe and reliable
devtools: Harden wizard invocation
info: Make project reporting resilient
init: Handle skipped setup steps
test: Resolve test utils from project
typecheck: Avoid unnecessary preparation
upgrade: Recreate selected workspace lockfile
upgrade: Handle unsupported dedupe
module: Harden module management flows
add: Respect project registry configuration
build: Propagate failures and honor bare profile flag
dev: Isolate internal test overrides
dev: Harden listener edge cases
preview: Handle listen options and output fallback
start: Execute Nitro preview commands faithfully
cli: Cap and score-filter module search results
deps: Upgrade to fuzzysort v4
dev,info: Print nitro version nuxt depends on
dev: Use a strict port when _PORT is provided to _dev
dev: Close the listener when setup fails after binding
Do not mistake a --cwd value for the command
dev: Validate lock and worker metadata before trusting it
init: Only send GITHUB_TOKEN to github hosts
add: Refuse to write a template outside the project
dev: Reject a cloudflared version that escapes the release url or cache
module: Refuse to add a config key a spread or computed key could shadow
module,upgrade: Resolve npmrc credentials as npm does, falling back to npm
module: Drop Nuxt 2 leftovers from module search
module: Keep the closing bracket when removing consecutive inline entries
dev: Honour a bare --profile flag
dev: Recommend a CA root instead of disabling TLS verification
init: Use a consistent separator in template lists
Patch citty with hidden, multiple and inherit arg support
dev: Serve the loading page Nuxt would render, and stop it reloading itself
dev: Disable timestamps on the project's consola instance
add-template: Declare shorthand modifier flags
Add value hints to string args
init: Pass -- through npm create, document negative flags
capture: Sample fingerprint where output is erased
dev: Handle nuxt v5 for the new interactive ui
typecheck: Document negatable flags
dev: Properly attribute logs for nitro v3
Abort on ctrl-c at suggestion prompts
dev: Close the help view with ? as well as h
dev: Group routes by kind and label method-less handlers
dev: Stop racing the first render
docs: Reject unsafe tarball members before extraction
dev: Verify sha-256 checksums for downloaded cloudflared binaries
dev: Omit request headers from the rendered error page
dev: Strip the request attribution header from incoming requests
dev: Reject unknown Host headers on internal dev endpoints
Only report unknown flags that look like a typo
dev: Record request urls before middlewares rewrite them
dev: Surface boxed prompts + startup warnings on the panel
dev: Only draw the startup QR code in a terminal
cli: Drop clack gutter framing from redirected output
dev: Suggest a route that exists, only where it can be read
curl: Suggest a path every project serves when the URL is missing
dev: Time startup phases + stop hook names leaking into labels
add: Stop an entry's trailing comment swallowing a new separator
build,dev: Return the path the cpu profile was written to
analyze,build,dev,preview: Server build descriptor with nitro fallback
Report actual server health and error remedies
docs: Scope cache to registry and strip control characters
dev,curl,task: Ignore lock file urls that don't match machine
analyze: Check host header on analyze stats server
Ignore project .npmrc for background update check
dev: Do not infer public mode from a non-loopback host
dev: Stop the selection at both ends of a view
dev: Pass the request through to the error channel
dev: Show an app log once when a fork serves it
dev: Repaint the panel on a clean screen after a resize
dev: Require a loopback peer for the error channel
dev: Add actionable error for missing cert file
dev: Handle keyboard input before dev server is up + running
dev: Read a key that shares a chunk with a terminal reply
dev: Omit error history from failure pages for remote peers
dev: Serve the error channel to remote peers, scoped
dev: Mint request ids from a random source
dev: Attribute requests at the nitro fetch level, leaving id header
dev: Forcibly close websocket connections when quitting
dev: End the process when ctrl-c arrives early
dev: Open inspector in nitro dev worker
dev: Hotfix by force closing nitro sockets
dev: Open nitro worker inspector from a plugin
Skip corepack when it is not on the PATH
Use setGlobalProxyFromEnv to enable proxy
Rewrap console before reporting a failed command
Avoid spinner frames + ansi help when not a tty
Migrate to package-manager-detector
dev: Skip reloads after dev server has shut down
Quote retry command arguments so they aren't expanded
dev: Measure wide characters when laying out tui
dev: Close vite hmr upgrades that arrive before vite attaches
dev: Leave build asset upgrades to the bundler
dev: Make keyboard shortcuts more consistent
dev: Let a restarted fork reload changed .env values

Chore

breaking
⚠️ Bump node versions to support native typescript importing
breaking
⚠️ Require node 22.21+ and drop env proxy support detection

Breaking Changes

breaking
nuxi: ⚠️ Defer to project cli + drop nuxt <3.26 support
breaking
init: ⚠️ Drop init command from @nuxt/cli
breaking
⚠️ Bump node versions to support native typescript importing
breaking
⚠️ Require node 22.21+ and drop env proxy support detection

3.x · maintenance
3.37.0
14 Jul 2026
3.36.1
26 Jun 2026
3.36.0
20 Jun 2026

Notes older than 90 days are read on the Releases tab.

Dependency tracking · free for 3 projects

Know when your own dependencies move

@nuxt/cli shipped a new major in the last 12 months, among 17 releases. Inlinr shows which of your projects are behind, and what the upgrade breaks.

Advisories reach you
An email when a critical or high advisory affects a project, before the next install.
Upgrades checked first
Peer ranges, Node, ESM-only and types changes read before you bump.
Only what matters
Majors and breaking notes stay; patches and sibling bumps fold into one line.

How dependency tracking works

Registry facts last checked 21 Oct 2026. Releases and advisories last read 21 Oct 2026.

Latest releases

4.0.1

4.0.0

3.37.0

3.36.1

3.36.0

Know when your own dependencies move