Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

The tty module in Node.js

Explains the Node.js tty module: tty.isatty(), process.stdout.isTTY, columns and rows, color support, raw mode, and how to behave when output is piped.

A TTY is a terminal: an interactive device with a keyboard and a screen. Programs behave differently when talking to one. They color their output, redraw progress bars, ask questions, and size tables to the window width. When output is piped to a file or another program, they should switch all of that off.

The node:tty module is how Node tells the two cases apart. tty.isatty(fd) answers for any file descriptor. When process.stdin or process.stdout is a terminal, Node creates tty.ReadStream and tty.WriteStream objects for them, which add terminal-only features such as columns, rows, getColorDepth() and setRawMode(). When they are not terminals, those properties are simply missing.

NODE
import tty from "node:tty";

console.log(tty.isatty(0), tty.isatty(1), tty.isatty(2));

Try it

Node.js Detect a terminal and adapt

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 A helper that formats for width

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.

What the module provides

  • tty.isatty(fd) returns true when the file descriptor fd (an integer) refers to a terminal. It returns false for non-integers and for descriptors that are not open. 0, 1 and 2 are stdin, stdout and stderr.
  • process.stdout.isTTY and process.stdin.isTTY are true on terminals and undefined otherwise (not false), so test with === true or Boolean().
  • tty.WriteStream (the type of process.stdout on a terminal) has columns, rows, getWindowSize(), getColorDepth(), hasColors(count) and emits resize when the window changes size.
  • tty.ReadStream (the type of process.stdin on a terminal) has isRaw and setRawMode(flag).
  • process.stdout.columns is the width in characters, for example 80 or 120. Re-read it inside a resize listener instead of caching it.

Raw mode

By default a terminal is in line mode: the operating system lets the user edit a line with backspace and delivers it only when Enter is pressed. process.stdin.setRawMode(true) turns that off, so every key reaches your program immediately and nothing is echoed. Use it for menus, editors and games, together with readline.emitKeypressEvents(). Remember that Ctrl+C is then an ordinary key, and always restore line mode with setRawMode(false) before exiting.

Usage notes

  • Never assume a terminal. Programs run in CI, in containers and under pipes (node app.js | less), where isTTY is not true and cursor tricks only corrupt the output.
  • The environment variables NO_COLOR and FORCE_COLOR are widely honored: NO_COLOR disables color, FORCE_COLOR enables it even when piped. util.styleText() already checks the stream it writes to.
  • getColorDepth() returns 1, 4, 8 or 24, the number of color bits the terminal supports, based on the environment.
  • stderr can be a terminal while stdout is piped, and the other way round. Check each stream you write to.
  • You rarely construct tty.ReadStream or tty.WriteStream yourself; use the process streams.