repl: use inspector over vm by avivkeller · Pull Request #64034 · nodejs/node

avivkeller · 2026-06-20T21:46:39Z

This PR switches the REPL from node:vm to node:inspector, moving it from a synchronous to an asynchronous evaluator. This brings the following improvements:

Top-level await is now natively supported by the inspector, so --no-experimental-repl-await is no longer accepted. This also resolves a known limitation where TLA would invalidate the lexical scoping of const declarations.
Static imports such as import ... from '...' are now transformed into real dynamic imports and executed, rather than throwing Cannot use import statement outside a module with a hint to rewrite the import manually. This isn't strictly required by removing node:vm, but the change makes it easier. I can split this into a separate PR if preferred.
Several node:vm issues are resolved (see the list below), and users can now attach process listeners without breaking the REPL.
Errors are more detailed: for example, showing the specific line in a .load-ed file where an error was thrown.

This is a semver-major change; see the reasons listed in the notable changes section.

Removed Tests

addons/repl-domain-abort, parallel/test-repl-domain.js: We no longer rely on the domain module, so testing it is no longer needed.
- parallel/test-repl-no-terminal-restore-process-listeners.js: An extension of the above — we no longer modify the ability to set process listeners.
- parallel/test-repl-uncaught-exception-async.js / parallel/test-repl-uncaught-exception.js / parallel/test-repl-tab-complete-nested-repls.js: An extension of the above; this test case no longer throws an error.
known_issues/test-repl-require-context.js: This known issue has been resolved.
parallel/test-repl-top-level-await.js: No need to test TLA — it's supported natively by the inspector.
- parallel/test-repl-preprocess-top-level-await.js: An extension of the above; the REPL no longer pre-processes top-level await.
parallel/test-repl-preview-without-inspector.js: The REPL no longer works without the inspector.
parallel/test-util-sigint-watchdog.js: This tested code that has been removed as part of this migration.
pseudo-tty/repl-dumb-tty.js: There's currently no way to conditionally run these tests (run only when inspector is available).

Fixes: #64523
Closes: #64534

Fixes: #39387
Closes: #39392

Fixes: #61390
Fixes: #63126
Fixes: #38503
Fixes: #37445
Fixes: #38145
Fixes: #33369
Fixes: #48131
Fixes: #8309
Fixes: #39689
Fixes: #18931

Notable Change

The REPL has been re-implemented on top of the V8 Inspector (node:inspector) rather than node:vm. This moves the REPL from a synchronous to an asynchronous evaluator and resolves long-standing design quirks that stemmed from the vm-based design:

Because the inspector natively supports top-level await, the --no-experimental-repl-await flag is no longer accepted, and top-level await no longer corrupts the lexical scoping of const/let declarations. Additionally, statements that would normally return a Promise are now awaited until they settle.
Lines such as import { readFile } from 'node:fs/promises' are now transformed into real dynamic imports and executed.
_ and _error are available even in REPLs with a modified context.
Users can now add listeners (e.g. uncaughtException) without disrupting evaluation.
Throwing inside queueMicrotask/timer callbacks, and vm async timeouts, no longer take down the process.
Certain side-effect free Proxy's, Getters, and other non-static properties can be tab/auto-completed.
And more

Breaking changes

In addition to the removal of --no-experimental-repl-await and similar await changes noted above:

Because errors now surface through the inspector, their output (including the added detail) can differ from previous releases. Code or tests that match on exact REPL error or stack-trace text may need to be updated.
The caret/offset indicator that pointed at the precise location of a SyntaxError is no longer emitted in the main REPL; this information is still available programmatically in the stack trace.
V8's Inspector does not carry RegExp matches over to the global object across multiple evaluations.

nodejs-github-bot · 2026-06-20T21:46:44Z

Review requested:

@nodejs/config

avivkeller · 2026-06-22T00:08:54Z

cc @nodejs/repl @nodejs/inspector

github-actions · 2026-06-22T00:22:57Z

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @avivkeller.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

nodejs-github-bot · 2026-06-23T02:16:53Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74373/

nodejs-github-bot · 2026-06-23T07:13:11Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74377/

qwitwa · 2026-06-24T06:11:29Z

Does this change make tab-completions side-effect free in all cases?
(I ended up here after clicking through completion side-effect issues)
I see regex and generator side effects in the linked issues; my case was with dax's $ tag function, where

await $`echo hello`.sometext

was printing hello whilst tab completing.

avivkeller · 2026-06-24T11:28:21Z

Hi @qwitwa! Unfortunately, that specific case is not resolved by this PR. Although, that might be an issue with V8, since the REPL relies on CDP's throwOnSideEffect, which determines $ as side-effect free (even though, apparently, it's not)

avivkeller · 2026-06-26T16:29:58Z

Bump @nodejs/repl @nodejs/vm @nodejs/inspector

panva

LGTM

nodejs-github-bot · 2026-07-18T16:25:18Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74880/

nodejs-github-bot · 2026-07-18T17:54:29Z

CI: https://ci.nodejs.org/job/node-test-pull-request/74881/

mcollina

lgtm

nodejs-github-bot · 2026-07-18T19:40:17Z

Commit Queue failed

- Loading data for nodejs/node/pull/64034
✔  Done loading data for nodejs/node/pull/64034
----------------------------------- PR info ------------------------------------
Title      repl: use inspector over vm (#64034)
Author     Aviv Keller <[email protected]> (@avivkeller)
Branch     avivkeller:repl-inspector -> nodejs:main
Labels     c++, repl, semver-major, lib / src, notable-change, author ready, needs-ci, review wanted, commit-queue-squash
Commits    9
 - repl: use inspector over vm
 - fixup!
 - fixup!
 - fixup!
 - fixup! remove file from testing
 - fixup!
 - fixup!
 - fixup!
 - fixup!
Committers 2
 - avivkeller <[email protected]>
 - GitHub <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/64034
Fixes: https://github.com/nodejs/node/issues/64523
Fixes: https://github.com/nodejs/node/pull/64534
Fixes: https://github.com/nodejs/node/issues/39387
Fixes: https://github.com/nodejs/node/pull/39392
Fixes: https://github.com/nodejs/node/issues/61390
Fixes: https://github.com/nodejs/node/issues/63126
Fixes: https://github.com/nodejs/node/issues/38503
Fixes: https://github.com/nodejs/node/issues/37445
Fixes: https://github.com/nodejs/node/issues/38145
Fixes: https://github.com/nodejs/node/issues/33369
Fixes: https://github.com/nodejs/node/issues/48131
Fixes: https://github.com/nodejs/node/issues/8309
Fixes: https://github.com/nodejs/node/issues/39689
Fixes: https://github.com/nodejs/node/issues/18931
Reviewed-By: Dario Piotrowicz <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Filip Skokan <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/64034
Fixes: https://github.com/nodejs/node/issues/64523
Fixes: https://github.com/nodejs/node/pull/64534
Fixes: https://github.com/nodejs/node/issues/39387
Fixes: https://github.com/nodejs/node/pull/39392
Fixes: https://github.com/nodejs/node/issues/61390
Fixes: https://github.com/nodejs/node/issues/63126
Fixes: https://github.com/nodejs/node/issues/38503
Fixes: https://github.com/nodejs/node/issues/37445
Fixes: https://github.com/nodejs/node/issues/38145
Fixes: https://github.com/nodejs/node/issues/33369
Fixes: https://github.com/nodejs/node/issues/48131
Fixes: https://github.com/nodejs/node/issues/8309
Fixes: https://github.com/nodejs/node/issues/39689
Fixes: https://github.com/nodejs/node/issues/18931
Reviewed-By: Dario Piotrowicz <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Filip Skokan <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Sat, 20 Jun 2026 21:46:39 GMT
   ✔  Approvals: 3
   ✔  - Dario Piotrowicz (@dario-piotrowicz): https://github.com/nodejs/node/pull/64034#pullrequestreview-4675448876
   ✔  - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/64034#pullrequestreview-4729043601
   ✔  - Filip Skokan (@panva) (TSC): https://github.com/nodejs/node/pull/64034#pullrequestreview-4728817049
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2026-07-18T17:54:29Z: https://ci.nodejs.org/job/node-test-pull-request/74881/
- Querying data for job/node-test-pull-request/74881/
✔  Build data downloaded
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 64034
From https://github.com/nodejs/node
 * branch                  refs/pull/64034/merge -> FETCH_HEAD
✔  Fetched commits as 9df0e9b4d4a5..e90cd833579c
--------------------------------------------------------------------------------
Auto-merging doc/api/errors.md
Auto-merging lib/repl.js
[main a796734305] repl: use inspector over vm
 Author: avivkeller <[email protected]>
 Date: Sat Jun 20 17:45:59 2026 -0400
 126 files changed, 3119 insertions(+), 4299 deletions(-)
 delete mode 100644 lib/internal/repl/await.js
 create mode 100644 lib/internal/repl/eval.js
 create mode 100644 lib/internal/repl/inspector.js
 create mode 100644 lib/internal/repl/transform.js
 delete mode 100644 test/addons/repl-domain-abort/binding.cc
 delete mode 100644 test/addons/repl-domain-abort/binding.gyp
 delete mode 100644 test/addons/repl-domain-abort/test.js
 delete mode 100644 test/fixtures/repl-tab-completion-nested-repls.js
 delete mode 100644 test/known_issues/test-repl-require-context.js
 delete mode 100644 test/parallel/test-repl-autolibs.js
 create mode 100644 test/parallel/test-repl-autolibs.mjs
 rename test/parallel/{test-repl-context.js => test-repl-context.mjs} (83%)
 delete mode 100644 test/parallel/test-repl-definecommand.js
 create mode 100644 test/parallel/test-repl-definecommand.mjs
 delete mode 100644 test/parallel/test-repl-domain.js
 rename test/parallel/{test-repl-editor.js => test-repl-editor.mjs} (78%)
 delete mode 100644 test/parallel/test-repl-function-definition-edge-case.js
 create mode 100644 test/parallel/test-repl-function-definition-edge-case.mjs
 rename test/parallel/{test-repl-inspector.js => test-repl-inspector.mjs} (64%)
 rename test/parallel/{test-repl-load-multiline-no-trailing-newline.js => test-repl-load-multiline-no-trailing-newline.mjs} (56%)
 rename test/parallel/{test-repl-load-multiline.js => test-repl-load-multiline.mjs} (52%)
 delete mode 100644 test/parallel/test-repl-no-terminal-restore-process-listeners.js
 delete mode 100644 test/parallel/test-repl-preprocess-top-level-await.js
 delete mode 100644 test/parallel/test-repl-pretty-custom-stack.js
 create mode 100644 test/parallel/test-repl-pretty-custom-stack.mjs
 delete mode 100644 test/parallel/test-repl-pretty-stack-custom-writer.js
 create mode 100644 test/parallel/test-repl-pretty-stack-custom-writer.mjs
 delete mode 100644 test/parallel/test-repl-pretty-stack.js
 create mode 100644 test/parallel/test-repl-pretty-stack.mjs
 delete mode 100644 test/parallel/test-repl-preview-newlines.js
 create mode 100644 test/parallel/test-repl-preview-newlines.mjs
 delete mode 100644 test/parallel/test-repl-preview-without-inspector.js
 rename test/parallel/{test-repl-preview.js => test-repl-preview.mjs} (65%)
 delete mode 100644 test/parallel/test-repl-recoverable.js
 create mode 100644 test/parallel/test-repl-recoverable.mjs
 delete mode 100644 test/parallel/test-repl-sigint-nested-eval.js
 delete mode 100644 test/parallel/test-repl-tab-complete-buffer.js
 create mode 100644 test/parallel/test-repl-tab-complete-buffer.mjs
 delete mode 100644 test/parallel/test-repl-tab-complete-nested-repls.js
 delete mode 100644 test/parallel/test-repl-top-level-await.js
 delete mode 100644 test/parallel/test-repl-uncaught-exception-async.js
 delete mode 100644 test/parallel/test-repl-uncaught-exception-standalone.js
 create mode 100644 test/parallel/test-repl-uncaught-exception-standalone.mjs
 delete mode 100644 test/parallel/test-repl-uncaught-exception.js
 delete mode 100644 test/parallel/test-repl-underscore.js
 create mode 100644 test/parallel/test-repl-underscore.mjs
 delete mode 100644 test/parallel/test-repl-use-global.js
 create mode 100644 test/parallel/test-repl-use-global.mjs
 delete mode 100644 test/parallel/test-util-sigint-watchdog.js
 delete mode 100644 test/pseudo-tty/repl-dumb-tty.js
 delete mode 100644 test/pseudo-tty/repl-dumb-tty.out
[main f5a0f14734] fixup!
 Author: avivkeller <[email protected]>
 Date: Mon Jul 13 18:03:34 2026 -0700
 5 files changed, 64 insertions(+), 21 deletions(-)
 create mode 100644 test/parallel/test-repl-promise-gc.mjs
error: The following untracked working tree files would be overwritten by merge:
	output
Please move or remove them before you merge.
Aborting
fatal: cherry-pick failed
[main 065e945eaa] fixup!
 Author: avivkeller <[email protected]>
 Date: Mon Jul 13 18:07:27 2026 -0700
 2 files changed, 4 insertions(+), 1 deletion(-)
   ✘  Failed to apply patches

https://github.com/nodejs/node/actions/runs/29658096987

Signed-off-by: Aviv Keller <[email protected]> PR-URL: #64034 Fixes: #64523 Closes: #64534 Fixes: #39387 Closes: #39392 Fixes: #61390 Fixes: #63126 Fixes: #38503 Fixes: #37445 Fixes: #38145 Fixes: #33369 Fixes: #48131 Fixes: #8309 Fixes: #39689 Fixes: #18931 Reviewed-By: Dario Piotrowicz <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Filip Skokan <[email protected]>

avivkeller · 2026-07-18T20:00:04Z

Landed in 4f844f4

Auto commit queue failed because:

Closes: PRs were rewritten as Fixes:, which was incorrect metadata
It failed to correctly squash commits, which, ran git node land was run locally, did correctly

aduh95 · 2026-08-03T16:16:10Z

-  AddOption("--experimental-repl-await",
-            "experimental await keyword support in REPL",
-            &EnvironmentOptions::experimental_repl_await,
-            kAllowedInEnvvar,
-            true);


We need to reintroduce this flag as a no-op

Why? This is semver-major, isn't it fine to make flags stop working?

Nope, when a feature is unflagged, we always keep the flag: the cost of keeping a flag is marginal, while for the ecosystem it's unnecessary churn

Two doc-only improvements to `doc/api/repl.md`, both filling gaps left by recent semver-major REPL changes: 1. `repl.REPLServer` is an ES class; calling it without `new` is End-of-Life (DEP0185) and throws a native V8 `TypeError`. The "Class: REPLServer" section now notes this and links to the DEP0185 entry in `doc/api/deprecations.md`. No `Stability: 0` banner is added because the class itself is not deprecated — only the `new`-less invocation is — matching the parallel DEP0184/DEP0195 "classes without `new`" convention. 2. PR nodejs#64034 ("repl: use inspector over vm") removed the old "Global uncaught exceptions" subsection because the `domain`-based restrictions it documented no longer exist. A new top-level `### Error handling` section documents the current model (mirroring the `### Error handling` convention in async_hooks/http2/quic), anchored to the existing `Uncaught Error: REPL await` example. Refs: nodejs#59495 Refs: nodejs#54869 Refs: nodejs#54842 Refs: nodejs#64034 PR-URL: nodejs#64993 Signed-off-by: Adrian Estrada <[email protected]>

Two doc-only improvements to `doc/api/repl.md`, both filling gaps left by recent semver-major REPL changes: 1. `repl.REPLServer` is an ES class; calling it without `new` is End-of-Life (DEP0185) and throws a native V8 `TypeError`. The "Class: REPLServer" section now notes this and links to the DEP0185 entry in `doc/api/deprecations.md`. No `Stability: 0` banner is added because the class itself is not deprecated — only the `new`-less invocation is — matching the parallel DEP0184/DEP0195 "classes without `new`" convention. 2. PR #64034 ("repl: use inspector over vm") removed the old "Global uncaught exceptions" subsection because the `domain`-based restrictions it documented no longer exist. A new top-level `### Error handling` section documents the current model (mirroring the `### Error handling` convention in async_hooks/http2/quic), anchored to the existing `Uncaught Error: REPL await` example. Refs: #59495 Refs: #54869 Refs: #54842 Refs: #64034 Signed-off-by: Adrian Estrada <[email protected]> PR-URL: #64993 Reviewed-By: Erick Wendel <[email protected]> Reviewed-By: Ulises Gascón <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]>

avivkeller marked this pull request as draft June 20, 2026 21:46

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Jun 20, 2026

addaleax added the semver-major PRs that contain breaking changes and should be released in the next major version. label Jun 20, 2026

avivkeller added the repl Issues and PRs related to the REPL subsystem. label Jun 20, 2026

avivkeller force-pushed the repl-inspector branch 4 times, most recently from 9fdad96 to 56ebb41 Compare June 21, 2026 23:58

avivkeller changed the title ~~[WIP] repl: use inspector over vm~~ repl: use inspector over vm Jun 22, 2026

avivkeller marked this pull request as ready for review June 22, 2026 00:03

avivkeller force-pushed the repl-inspector branch 2 times, most recently from 3f34721 to d7534b9 Compare June 22, 2026 00:07

avivkeller added the notable-change PRs with changes that should be highlighted in changelogs. label Jun 22, 2026

avivkeller force-pushed the repl-inspector branch 2 times, most recently from 012ec64 to e428a2e Compare June 22, 2026 20:28

avivkeller added the commit-queue-squash PRs the Commit Queue should land as one squashed commit. label Jun 23, 2026

avivkeller force-pushed the repl-inspector branch from 33e1f17 to a949698 Compare June 23, 2026 00:59

avivkeller added the review wanted PRs that need review. label Jun 26, 2026

avivkeller force-pushed the repl-inspector branch from a949698 to ff79eed Compare June 27, 2026 21:45

This comment was marked as off-topic.

Sign in to view

avivkeller requested a review from panva July 18, 2026 15:58

panva approved these changes Jul 18, 2026

View reviewed changes

panva added the request-ci Add this label to start a Jenkins CI on a PR. label Jul 18, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jul 18, 2026

avivkeller added 3 commits July 18, 2026 09:27

fixup!

f7bfe2a

fixup!

b000505

fixup!

e90cd83

mcollina approved these changes Jul 18, 2026

View reviewed changes

avivkeller added commit-queue-squash PRs the Commit Queue should land as one squashed commit. commit-queue PRs queued for automated landing through the Commit Queue. labels Jul 18, 2026

nodejs-github-bot added commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. and removed commit-queue PRs queued for automated landing through the Commit Queue. labels Jul 18, 2026

avivkeller closed this Jul 18, 2026

avivkeller mentioned this pull request Jul 19, 2026

test: resolve flaky repl test #64594

Closed

nbbeeken mentioned this pull request Jul 20, 2026

chore(ci): fix windows e2e with server pin, upgrade OS for nightlies and add skips, skip vscode tests, fix evergreen warnings mongodb-js/mongosh#2774

Merged

This was referenced Jul 26, 2026

repl: Runtime.awaitPromise races with GC when objectGroup is not passed Body #64762

Closed

repl: pass objectGroup to Runtime.awaitPromise to prevent GC collection #64764

Closed

aduh95 reviewed Aug 3, 2026

View reviewed changes

avivkeller mentioned this pull request Aug 3, 2026

cli: add No-Op --experimental-repl-await #64986

Closed

edsadr mentioned this pull request Aug 3, 2026

doc: document REPL DEP0185 throws and uncaught-exception behavior #64993

Merged

MikeMcC399 mentioned this pull request Aug 27, 2026

REPL spamming and stuck when Promise.any([]). is typed #65581

Open

Uh oh!

Uh oh!

Conversation

avivkeller commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Removed Tests

Notable Change

Breaking changes

Uh oh!

nodejs-github-bot commented Jun 20, 2026

Uh oh!

avivkeller commented Jun 22, 2026

Uh oh!

github-actions Bot commented Jun 22, 2026

Uh oh!

nodejs-github-bot commented Jun 23, 2026

Uh oh!

nodejs-github-bot commented Jun 23, 2026

Uh oh!

qwitwa commented Jun 24, 2026

Uh oh!

avivkeller commented Jun 24, 2026

Uh oh!

avivkeller commented Jun 26, 2026

Uh oh!

This comment was marked as off-topic.

panva left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Jul 18, 2026

Uh oh!

nodejs-github-bot commented Jul 18, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Jul 18, 2026

Uh oh!

avivkeller commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aduh95 Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

avivkeller commented Jun 20, 2026 •

edited

Loading

avivkeller commented Jul 18, 2026 •

edited

Loading