Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js repl.start() method

Reference for repl.start() in Node.js: build a custom read-eval-print loop with your own streams, context, commands, eval function and writer.

repl.start() creates an interactive read-eval-print loop, the same thing you get when you run node with no arguments. Because it takes any input and output streams, you can embed a REPL in your own tool: an admin console over a socket, a debugging prompt inside a running server, or a scripting shell with your own objects and commands.

It returns a REPLServer, an event emitter that lets you add variables to the evaluation scope, define dot-commands and react to the loop closing.

NODE
import repl from 'node:repl';

const server = repl.start({ prompt: 'app> ' });
server.context.version = '1.0';

Try it

Node.js A REPL driven by streams

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Custom commands and a custom writer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
repl.start([options]): REPLServer
repl.start(prompt): REPLServer
Option Description
prompt The prompt string. Default is '> '.
input, output Readable and writable streams. Default process.stdin and process.stdout.
terminal Treat the streams as a TTY (colors, line editing). Defaults to output.isTTY.
useColors Color the output of the default writer.
useGlobal If true, evaluate in the real global object instead of a separate context. Default false.
ignoreUndefined Do not print undefined results. Default false.
writer Function that turns a result into the printed string. Default is util.inspect.
eval Custom (cmd, context, filename, callback) evaluator, for example to support another language.
preview Show inline previews of completions and results (on by default in a terminal).
replMode repl.REPL_MODE_SLOPPY (default) or repl.REPL_MODE_STRICT.
breakEvalOnSigint Stop a running evaluation on Ctrl+C. Cannot be combined with a custom eval.

Returns: a REPLServer with context, defineCommand(keyword, cmd), displayPrompt(), clearBufferedCommand(), setupHistory(file, callback), close() and the events 'exit' and 'reset'.

Usage notes

  • Own context by default. Variables set on server.context are visible as globals inside the REPL. The built-in modules (fs, path, ...) are available without require. With the default useGlobal: false, .clear resets the context and emits 'reset'; re-add your variables in a 'reset' handler.
  • Top-level await works in the REPL, as in the standard node REPL.
  • Errors are printed, not thrown. An unknown identifier prints a ReferenceError to the output stream and the loop goes on.
  • A REPL is not a sandbox. Anyone who can type into it controls the process. If you expose it over a socket, bind to 127.0.0.1 or a Unix socket and require authentication outside the REPL. See vm is not a sandbox.
  • History. server.setupHistory('/path/file', cb) persists commands between sessions; the default REPL uses NODE_REPL_HISTORY.
  • Built-in commands: .help, .break, .clear, .editor, .exit, .load, .save. _ holds the last result and _error the last error.
  • Multi-line input is detected automatically: an incomplete expression continues on the next line.
  • Custom evaluators receive input with a trailing newline and must call the callback exactly once; throw new repl.Recoverable(err) to ask for more input.