node-pty

node-pty is Microsoft’s native addon that exposes forkpty(3)-style pseudoterminal bindings to Node.js, letting an application spawn a shell or any other process behind a real PTY instead of a plain pipe. Because the child believes it is talking to an actual terminal, programs that emit control sequences, resize themselves, or need line-discipline behavior work exactly as they would in a native terminal.

It powers the integrated terminal in Visual Studio Code as well as terminal emulators like Hyper, Theia, and Extraterm, and it bridges the platform gap by using conpty on modern Windows and native forkpty on Linux/macOS behind one consistent API.

What You Get

• A pty.spawn() API that forks any executable behind a pseudoterminal and returns a terminal object with onData, write, resize, and kill
• Cross-platform parity via native forkpty on Linux/macOS and the Windows ConPTY API on Windows 10 1809+
• TypeScript type declarations for the full public API (typings/node-pty.d.ts)
• Automatic flow control support (XON/XOFF or custom pause/resume sequences) to avoid overwhelming child processes
• Prebuilt native binaries fetched at install time, falling back to node-gyp rebuild from source

Common Use Cases

• Building a terminal emulator UI in a desktop or web app (e.g. paired with xterm.js)
• Embedding an interactive shell inside an Electron or VS Code-style IDE
• Driving CLI tools that require an attached TTY to behave correctly (interactive prompts, progress bars, color output)
• Building browser-based terminal-over-HTTP tools like web SSH clients

Under The Hood

Architecture - node-pty splits into a thin TypeScript dispatch layer (src/index.ts) that picks UnixTerminal or WindowsTerminal at require-time based on process.platform, and a native binding compiled per-platform (C++ under src/unix/src/win) that actually calls forkpty(3) or the Windows ConPTY API; a worker subdirectory offloads the Windows console-list agent to a child process so the main thread stays responsive. Tech Stack - TypeScript for the public API and tests (mocha), C++ for the native addon built via node-gyp/binding.gyp and node-addon-api, with prebuilt binaries fetched by scripts/prebuild.js at install time and a node-gyp rebuild fallback. Code Quality - the repo carries real unit tests (terminal.test.ts, unixTerminal.test.ts, windowsTerminal.test.ts, eventEmitter2.test.ts) run via mocha plus ESLint enforced as a post-test step, and TypeScript typings are hand-maintained in typings/node-pty.d.ts as the API contract; native/platform code is comparatively harder to cover with automated tests and relies more on manual/CI verification across OSes. API Design - the public surface is deliberately small (spawn, deprecated fork/createTerminal aliases, and a returned terminal object exposing onData, write, resize, kill), which keeps the learning curve low, though Windows-vs-Unix option differences (e.g. IWindowsPtyForkOptions) leak into the typings and require platform awareness from consumers.