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.
import tty from "node:tty"; console.log(tty.isatty(0), tty.isatty(1), tty.isatty(2));
Try it
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.
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)returnstruewhen the file descriptorfd(an integer) refers to a terminal. It returnsfalsefor non-integers and for descriptors that are not open.0,1and2are stdin, stdout and stderr.process.stdout.isTTYandprocess.stdin.isTTYaretrueon terminals andundefinedotherwise (notfalse), so test with=== trueorBoolean().tty.WriteStream(the type ofprocess.stdouton a terminal) hascolumns,rows,getWindowSize(),getColorDepth(),hasColors(count)and emitsresizewhen the window changes size.tty.ReadStream(the type ofprocess.stdinon a terminal) hasisRawandsetRawMode(flag).process.stdout.columnsis the width in characters, for example 80 or 120. Re-read it inside aresizelistener 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), whereisTTYis not true and cursor tricks only corrupt the output. - The environment variables
NO_COLORandFORCE_COLORare widely honored:NO_COLORdisables color,FORCE_COLORenables 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.ReadStreamortty.WriteStreamyourself; use theprocessstreams.