@nuxt/cli

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

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:

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).

[!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

CI

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