v4.0.0-alpha.0

v4.0.0-alpha.0 is the first alpha release of @nuxt/cli v4 🎉

Timetable: 24 August

🎉 Highlights

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

🔥 in the six weeks since v3.37.0 we've merged 102 PRs and closed 93 issues. the CLI is also much slimmer: installed on its own it now pulls 34 packages and 2.3 MB of node_modules, rather than 74 and 9.1 MB.

An interactive dev server

nuxt dev now renders a panel with your server URLs, live startup progress, the current status and single-key shortcuts.

you can check logs, errors, served requests, routes, versions, and more behind keyboard shortcuts, or you can opt-into previous behaviour with --no-tui (or NUXT_TUI=plain)...

there should be a lot more information, such as why nuxt is restarting, and what bits of the startup cycle are taking time...

Talking to a running dev server

we now record dev server sessions in .nuxt/nuxt.lock, which enables a few new features:

nuxt curl sends a request to the dev server running for the project, so you don't need to know which port it ended up on. responses are reindented and highlighted in a terminal:

npx nuxt curl /api/hello -i
npx nuxt curl /api/todos -X POST -d '{"title":"Buy milk"}'

nuxt task list and nuxt task run do the same for Nitro tasks, against the server you already have running:

npx nuxt task run db:seed --payload.count=10

and a second nuxt dev will tell you that one is already running, and give you the choice to take it over from your current terminal if you want.

Smaller features

• nuxt docs "server routes" searches the docs for the Nuxt version the project depends on, and opens the best match.
• a mistyped command or flag is matched against the ones that exist and offered as a correction, rather than dumping help.
• nuxt add installs layers as well as modules, nuxt module search shows descriptions and highlights matches, and we now support --json for info, module search and task list.
• network failures explain themselves and suggest the retry likely to work (including NODE_EXTRA_CA_CERTS behind a proxy that re-signs TLS).
• pnpm catalogs are understood, so nuxt upgrade will work better...
• .... and lots more

⚠️ Breaking changes

we're also taking the opportunity to adopt the following breaking changes:

• we're dropping support for @nuxt/bridge (as Nuxt 2 has been EOL for some time now).
• we now require Node v22.19+, v24.11+, or v26+
• nuxi no longer bundles most commands; outside a project it defers to the project's own @nuxt/cli, and projects on Nuxt <3.26 are no longer supported by it
• nuxt init is gone from @nuxt/cli; scaffolding lives in create-nuxt (npm create nuxt)

🔥 Performance

against v3.37.0:

	v3.37.0	alpha.0	delta
nuxt --help	99ms	60ms	-40%
nuxt dev --help	80ms	48ms	-40%
modules loaded for nuxt dev --help	205	80	-61%
direct dependencies	28	21	-25%
installed packages	74	34	-54%
node_modules on disk	9.14MB	2.32MB	-75%
files installed	1274	419	-67%

you can track install size and dependency count here.

🧪 Trying it out

npm install -D @nuxt/cli@alpha

with pnpm you'll need to add an override, so Nuxt's own dependency resolves to the alpha too:

overrides:
  '@nuxt/cli': alpha

command docs are now generated from this repo and published at https://nuxt.com/docs/5.x/api/commands/.

🐛 Feedback

it's an alpha and much of the dev server is new, so expect breakage. the most likely candidates are the interactive UI in unusual terminals and multiplexers, restart/takeover behaviour, and Windows.

Tip

if you encounter issues, start by trying --no-tui and NUXT_IGNORE_LOCK=1.

please do open an issue with npx nuxt info output and a reproduction if you can 🙏

... and thank you to everyone in the nuxt community who's made this alpha possible! ❤️

👉 Changelog

compare changes

🚀 Enhancements

• dev: interactive terminal ui for the dev server (#1463)
• dev: suggest using nuxt curl when running non-interactively (#1464)
• dev: stream live startup progress to the loading page and terminal (81a5de1)
• offer to rerun with correct spelling of commands/args (36119fe)
• docs: add nuxt docs command (f2dbd8c)
• module,task: add --json to module search and task list (da95c8b)
• suggest the closest command instead of dumping help (b841b87)
• warn on unknown options and suggest the intended one (07e7981)
• info: add --json output (82fe2d6)
• dev: explain first-run failures before nuxt loads (#1444)
• curl,task: highlight + pretty-print responses (#1432)
• module: show descriptions and highlight matches while searching (e621b9c)
• curl,task: add nuxt curl, nuxt task list and nuxt task run (#1417)
• dev: take over a dev server already running on this project (#1414)
• improve upgrade hints + add init hint/tip (#1406)
• dev: print changed nuxt.config keys on a config-triggered reload (#1403)
• dev: report why the dev server reloaded or restarted (#1402)
• dev: surface the stackblitz editor url in the dev url block (62a030f)
• dev: hint about --host when bound to loopback in docker or wsl (29558d5)
• add: support adding layers via cli (#1399)
• support pnpm catalogs (#1397)
• build: report total build time (3d16e4c)
• nuxi: defer subcommands to the project's @nuxt/cli (#1394)
• init: opt yarn projects out of plug'n'play (64b4525)
• nudge when a newer nuxt release is available (#1393)
• suggest proxy-aware retry command when network fails (#1387)
• dev: add restart, url, qr and copy shortcuts (bf72c89)
• dev: support opening a custom path or url (f693d33)
• dev: add --strictPort flag (b6ee3b9)
• dev: respect BROWSER env when opening browser (c1c6687)
• dev: add q and quit shortcuts to dev server (#1378)
• dev: detect portless proxy urls (a0eace5)
• dev: better errors inspired by nitro (#1383)

🔥 Performance

• dev: bind the dev server port before the config is loaded (88de5da)
• keep engine and update checks off the version path (a3fa129)
• dev: stop saves that change nothing from restarting the dev server (#1435)
• module: swap fzf for fuzzysort (ff0cc23)
• dev,module: handle registry trailing slashes internally (0673103)
• dev: use node createHash for hashing build manifest (8ff1c67)
• dev: use builtin node SourceMap instead of source-map-js (#1430)
• info,upgrade: use confbox rather than pnpm-workspace-yaml (#1425)
• replace picocolors with node:util styleText (#1416)
• keep youch, the registry and the update check off startup (#1413)
• disable mimalloc eager arena commit at cli entry (#1411)
• ⚠️ nuxi: defer to project cli + drop nuxt <3.26 support (#1410)
• nuxi: do not bundle jiti (#1409)
• dev: warm a single fork by default, overridable with NUXT_DEV_FORK_POOL_SIZE (1897968)
• dev: warm the fork pool on first file change instead of on ready (9a10f71)

🩹 Fixes

• dev: stop racing the first render (#1475)
• dev: group routes by kind and label method-less handlers (9d042af)
• dev: close the help view with ? as well as h (6f6e530)
• abort on ctrl-c at suggestion prompts (34714dc)
• dev: properly attribute logs for nitro v3 (#1474)
• typecheck: document negatable flags (6890367)
• dev: handle nuxt v5 for the new interactive ui (#1473)
• capture: sample fingerprint where output is erased (#1472)
• init: pass -- through npm create, document negative flags (5d39ad0)
• add value hints to string args (#1468)
• add-template: declare shorthand modifier flags (#1467)
• dev: disable timestamps on the project's consola instance (#1460)
• dev: serve the loading page Nuxt would render, and stop it reloading itself (4d1edb4)
• patch citty with hidden, multiple and inherit arg support (#1457)
• init: use a consistent separator in template lists (013f43f)
• dev: recommend a CA root instead of disabling TLS verification (4b28edd)
• dev: honour a bare --profile flag (4af0dc3)
• module: keep the closing bracket when removing consecutive inline entries (14903e5)
• module: drop Nuxt 2 leftovers from module search (6d9bc86)
• module,upgrade: resolve npmrc credentials as npm does, falling back to npm (ed7c524)
• module: refuse to add a config key a spread or computed key could shadow (7ad4e6b)
• dev: reject a cloudflared version that escapes the release url or cache (7f02edf)
• add: refuse to write a template outside the project (29e69b9)
• init: only send GITHUB_TOKEN to github hosts (2a1e5b0)
• dev: validate lock and worker metadata before trusting it (53c42f1)
• do not mistake a --cwd value for the command (ec34eee)
• dev: close the listener when setup fails after binding (967f709)
• dev: use a strict port when _PORT is provided to _dev (#1456)
• dev,info: print nitro version nuxt depends on (#1454)
• deps: upgrade to fuzzysort v4 (#1443)
• cli: cap and score-filter module search results (75182da)
• start: execute Nitro preview commands faithfully (b80ed9c)
• preview: handle listen options and output fallback (0cf1306)
• dev: harden listener edge cases (a7add36)
• dev: isolate internal test overrides (5eee806)
• build: propagate failures and honor bare profile flag (8db925e)
• add: respect project registry configuration (e0a6164)
• module: harden module management flows (a08a775)
• upgrade: handle unsupported dedupe (33de9c8)
• upgrade: recreate selected workspace lockfile (292b63a)
• typecheck: avoid unnecessary preparation (07d86a3)
• test: resolve test utils from project (6ff5c36)
• init: handle skipped setup steps (00b2828)
• info: make project reporting resilient (9022816)
• devtools: harden wizard invocation (b6f2690)
• cleanup: make directory removal safe and reliable (9e3b1cb)
• analyze: guard builds and simplify serving (23a5a6c)
• add-template: expose template options (50e71e5)
• cli: align Node warning with package engines (634eeb7)
• cli: preserve local command failures (abfd7eb)
• dev: await close hooks on shutdown + warn on hanging processes (#1424)
• dev: restore isolated environment host defaults (#1422)
• dev: show loading screen in initial startup (#1421)
• ⚠️ init: drop init command from @nuxt/cli (#1420)
• dev: fall back to the project's loading template (#1419)
• correctly report Vite version when using Vite+ (#1415)
• dev: do not restart when a client aborts a connection (#1412)
• do not read the project manifest when a dependency is missing (aeb022e)
• dev: trace youch into dist so its assets ship with the build (#1407)
• dev: do not end the dev session when a replaced fork exits non-zero (4538067)
• resolve npm auth token from parseINI result (ec6b08a)
• dev: handle a rejected reusePort option and a failed cold restart (ae9be91)
• dev: keep serving during a hard restart using SO_REUSEPORT (#1404)
• dev: drain connections before force-closing the dev server (678348a)
• dev: omit default ports and decode urls in the dev url block (682c773)
• dev: warn on invalid --host and explain failed binds (98dcb1c)
• dev: keep warming the pool once the app is served by a fork (f93bd1d)
• dev: track cold forks in the pool so shutdown reaps them (dfef70f)
• dev: reap every pooled fork on shutdown (c16f02b)
• dev: bind directly with --strictPort and translate bind errors (747c898)
• analyze: skip prerendering routes when building (#1400)
• paths: emit clickable hyperlinks for printed paths (27d8296)
• don't mistake another package.json for nuxt's own (79a829d)
• dev: unpause stdin when using clack spinners on windows (#1395)
• stop forcing --no-clear on programmatic commands (2043313)
• dev: take us out of raw mode after clack finishes (5ef1f1b)
• match exsolve resolution errors when @nuxt/kit is missing (e7aa760)
• init: print cd step for single-character project directories (9ff68d9)
• dev: strip windows working directory from rendered errors (f6e9235)
• upgrade: take ownership of dependency installation (a04ec72)
• preview: declare serve as an optional peer dependency (846ebd5)
• dev: settle in-flight responses when nuxt reloads (#1392)
• upgrade: find lockfile in nearest directory, not workspace root (#1391)
• dev: open inspector only in the process serving the app (#1388)
• typecheck: only imply --build for solution-style tsconfigs (#1390)
• _dev,start: hide _dev and start commands from help output (#1389)
• remove duplicate, prefer 'nuxt' + add help snapshots (f9af294)
• dev: warn when a browser cannot be opened and caption qr codes (f1c378d)
• dev: do not report or restart on broken pipes (66d21bd)
• dev: ignore link-local addresses in network urls (56c1eb7)
• init: make dependency install recoverable and package-manager aware (#1386)
• dev: pin cloudflared version and shut tunnels down gracefully (0027fb2)
• dev: hide timestamp and remove outdated filters (cff4db2)

💅 Refactors

• share terminal background and brand colour detection (#1459)
• report first-run and lock failures as actionable errors (#1445)
• module: edit nuxt.config modules with oxc instead of magicast (97ded7d)
• fetch JSON with native fetch instead of ofetch (ea82130)
• info: load nuxt.config natively and make jiti an optional peer (669bc5e)
• module: search with fzf instead of fuse.js (297bf24)
• dev: use source-map-js to map error frames (4582c22)
• create-nuxt: bundle citty instead of depending on it (51849b8)
• normalise on rootDir in most usages (#1398)
• module: directly use magicast to update nuxt config (#1396)
• extract npm registry resolution into a shared util (571cc3a)
• move source of truth from nuxi to @nuxt/cli (#1385)
• dev: use internal listener (#1382)
• use picocolors (17b2d02)
• migrate from semver to verkit (#1379)
• replace debug with obug (#1372)

📖 Documentation

• correct conditional behaviour (c25d392)
• correct dev, analyze and init command details (41a9fe5)
• update docs for current v4 (#1471)
• move cli documentation into repository (#1465)

🏡 Chore

• bump uppt to v0.6.7 (fb86ed4)
• add a terminal capture harness and scenario fixtures (#1461)
• add a comparison benchmark harness (#1458)
• lint (51b98e0)
• note that init rejects where load reports (841fbc1)
• remove narration comments (99c0bb8)
• keep generated templates when the starter repo is unreachable (#1447)
• log manifest hash change before clearing build dir (585278a)
• exempt first-party packages from pnpm minimumReleaseAge (#1434)
• add new binary paths for nightly release (af14cc8)
• ⚠️ bump node versions to support native typescript importing (4360712)
• bump pnpm version (2bdae69)

✅ Tests

• freeze clock when testing startup logs (eacb946)
• mark bun websockets as supported + fix animation detection (63b5b7f)
• stop collecting scaffolded command fixtures as test files (a36ce44)
• stop the command e2e suite mutating the shared playground (bd19413)
• cover dev initialize wiring, close ordering and profiling (e32ea88)
• cover typecheck checker selection, install advice and build mode (1e3e803)
• cover upgrade preconditions, install failures and the pnpm catalog path (e12e139)
• cover the interactive init flow and its fallbacks (f8338be)
• cover the dev command takeover, handover and fork pool paths (8112e50)
• assert config edits hold their invariants across config shapes (672c101)
• cover the dev server lifecycle with a stubbed kit (dd68ab8)
• assert nuxt info reports config keys without their values (0b45675)
• cover registry auth scoping and dev server responses (3a5aa2c)
• cover console raw mode, config loading and info box formatting (ff8529a)
• cover error page rendering, cleanup guards and dev listen options (e991256)
• give servers under test a realistic startup budget (f1a664b)
• cover the banner path with a single version to join (a1a4cb9)
• give each dev fixture its own vite cache (e35dd95)
• generate: cover build overrides (f850a17)
• isolate runtime e2e ports in dev tests and fix force-kill (d05718d)
• give each dev spec its own fixture copy (fcfd1bf)
• stub provider and environment detection in dev output tests (d5c583e)
• use file URL when importing loader in subprocess (b6f5b11)
• fix types (a94b9f5)
• cover shortcut error paths (0e780ba)
• assert on rendered terminal output with ansivision (1754688)

🤖 CI

• update uppt to 0.6.5 and add prerelease trigger (46d0bef)
• only publish nightly releases from main (45a5d8f)
• run against 3.x branch as well (f1fcd22)
• trigger ci/lint jobs on merge group (9a95204)
• run pr benchmark against main (9dfa22b)
• set explicit permissions and avoid interpolation (ae1dfc2)
• set persist-credentials to false (09c49c4)
• also rename provenance workflow (df44f64)
• rename bench workflow (3798e0e)
• improve workflows (#1381)

🎉 New Contributors

• Norbiros (@Norbiros)
• Michał Kędrzyński (@kedrzu)
• Joaquín Sánchez (@userquin)
• Luke Nelson (@luc122c)

❤️ Contributors

• Daniel Roe (@danielroe)
• Norbiros (@Norbiros)
• Michał Kędrzyński (@kedrzu)
• Joaquín Sánchez (@userquin)
• Luke Nelson (@luc122c)