repository·main·Indexed 24 days ago
https://github.com/microsoft/node-ptyA Node.js library providing forkpty(3) bindings to spawn processes with pseudoterminal file descriptors. It is primarily used for building terminal emulators and running programs that require a TTY environment. Key features include the pty.spawn() method for creating ITerminal instances, support for XON/XOFF flow control, and platform-specific configurations for Unix and Windows (ConPTY). Version 1.1.0.
All processes launched via node-pty run at the same permission level as the parent process. If running in a server environment accessible via the internet, it is highly recommended to launch the pty inside a container to protect the host machine.
node-pty is not thread safe. Avoid running it across multiple worker threads in Node.js to prevent issues.
Flow control allows you to pause and resume the child process using XON/XOFF control codes. This can be enabled by setting handleFlowControl: true in the pty.spawn options or by setting ptyProcess.handleFlowControl = true on the instance.
By default, it uses:
PAUSE: \x13 (XOFF)RESUME: \x11 (XON)When flow control is enabled, these codes are not passed to the underlying pseudoterminal. You can customize these sequences using flowControlPause and flowControlResume in the constructor options to avoid conflicts with other environments.
const PAUSE = '\x13'; // XOFF
const RESUME = '\x11'; // XON
const ptyProcess = pty.spawn(shell, [], {handleFlowControl: true});
// flow control in action
ptyProcess.write(PAUSE); // pty will block and pause the child program
// ...
ptyProcess.write(RESUME); // pty will enter flow mode and resume the child program
// temporarily disable/re-enable flow control
ptyProcess.handleFlowControl = false;
// ...
ptyProcess.handleFlowControl = true;The Electron terminal example provides platform-specific scripts to handle dependency installation. Use the appropriate script for your operating system:
./npm-install.bat./npm-install.shTo use node-pty, you must install its dependencies and compile the C++ bindings.
Prerequisites:
Build Commands:
# Install dependencies and build C++
npm install
# Compile TypeScript -> JavaScript
npm run build# Install dependencies and build C++
npm install
# Compile TypeScript -> JavaScript
npm run buildBuilding node-pty requires specific system-level tools depending on your platform.
Install make, python, and build-essential:
sudo apt install -y make python build-essentialInstall Xcode from the App Store to compile sources.
npm install --global --production windows-build-toolsMSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)).This example demonstrates how to implement a terminal in Electron by using xterm.js in the renderer process and node-pty in the main process, communicating via IPC.
To run the example, follow these steps:
npm start.# Install dependencies (Windows)
./npm-install.bat
# Install dependencies (non-Windows)
./npm-install.sh
# Launch the app
npm startThe Terminal class supports automatic flow control to manage data transmission. When handleFlowControl is enabled in IPtyForkOptions, the terminal intercepts specific pause and resume sequences to prevent them from being forwarded to the underlying PTY. This is useful for avoiding conflicts with shell-level XON/XOFF control codes.
By default, the sequences used are:
\x13 (XOFF)\x11 (XON)You can customize these sequences by providing flowControlPause and flowControlResume in the IPtyForkOptions object.
Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d, it is typically caused by PowerShell being launched without the SystemRoot environment variable present.This manual test verifies that deeply nested process trees are correctly killed on Windows. When executed, it launches a Notepad window and a Webpack dev server. After 10 seconds, the Webpack dev server should be killed, while the Notepad instance should remain running. You can verify the kill was successful by checking Process Explorer or re-running the test.
npm i
node index.jsUse pty.spawn() to fork a process with a pseudoterminal file descriptor. This returns a terminal object that supports reading data, writing data, and resizing. This is the primary way to create a terminal emulator or run programs that require a TTY environment.
Common options for the spawn configuration include:
name: The terminal type (e.g., 'xterm-color').cols: Number of columns.rows: Number of rows.cwd: Current working directory.env: Environment variables.handleFlowControl: Boolean to enable automatic XON/XOFF flow control.import * as os from 'node:os';
import * as pty from 'node-pty';
const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
const ptyProcess = pty.spawn(shell, [], {
name: 'xterm-color',
cols: 80,
rows: 30,
cwd: process.env.HOME,
env: process.env
});
ptyProcess.onData((data) => {
process.stdout.write(data);
});
ptyProcess.write('ls\r');
ptyProcess.resize(100, 40);
ptyProcess.write('ls\r');On Windows, you can provide IWindowsPtyForkOptions to control specific ConPTY behaviors.
useConpty: Whether to use the ConPTY system. (Note: This option is deprecated and will be removed in a future version).useConptyDll: Use the ConPTY DLL.conptyInheritCursor: Whether the cursor is inherited in ConPTY.IPtyOpenOptions to specify the initial dimensions and encoding when opening an existing pty.