Fork pseudoterminals in Node.JS
npm install profoundjs-node-ptyprofoundjs-node-pty provides prebuilt N-API binaries for forward compatibility on Node versions 10 and later for these platforms:
- Darwin (Mac OS), ARM 64-bit
- Darwin (Mac OS), Intel 64-bit
- Linux, Intel/AMD 64-bit
- Linux, POWER 64-bit
- Windows, Intel/AMD 32-bit
- Windows, Intel/AMD 64-bit
forkpty(3) bindings for node.js. This allows you to fork processes with pseudoterminal file descriptors. It returns a terminal object which allows reads and writes.
node-pty supports Linux, macOS and Windows. Windows support is possible by utilizing the Windows conpty API on Windows 1809+ and the winpty library in older version.
w) to navigate to the correct version of the API.
js
var os = require("os");
var pty = require("node-pty");
var shell = os.platform() === "win32" ? "powershell.exe" : "bash";
var ptyProcess = pty.spawn(shell, [], {
name: "xterm-color",
cols: 80,
rows: 30,
cwd: process.env.HOME,
env: process.env,
});
ptyProcess.on("data", function (data) {
process.stdout.write(data);
});
ptyProcess.write("ls\r");
ptyProcess.resize(100, 40);
ptyProcess.write("ls\r");
`
Real-world Uses
node-pty powers many different terminal emulators, including:
- Microsoft Visual Studio Code
- Hyper
- Upterm
- Script Runner for Atom.
- Theia
- FreeMAN file manager
- terminus - An Atom plugin for providing terminals inside your Atom workspace.
- x-terminal - Also an Atom plugin that provides terminals inside your Atom workspace.
- Termination - Also an Atom plugin that provides terminals inside your Atom workspace.
- atom-xterm - Also an Atom plugin that provides terminals inside your Atom workspace.
- electerm Terminal/SSH/SFTP client(Linux, macOS, Windows).
- Extraterm
- Wetty Browser based Terminal over HTTP and HTTPS
- nomad
- DockerStacks Local LAMP/LEMP stack using Docker
- TeleType: cli tool that allows you to share your terminal online conveniently. Show off mad cli-fu, help a colleague, teach, or troubleshoot.
Do you use node-pty in your application as well? Please open a Pull Request to include it here. We would love to have it in our list.
Building
`bash
Install dependencies and build C++
npm install
Compile TypeScript -> JavaScript
npm run build
`
Dependencies
$3
`
sudo apt install -y make python build-essential
`
The following are also needed:
- Node.JS 10+
$3
Xcode is needed to compile the sources, this can be installed from the App Store.
$3
npm install requires some tools to be present in the system like Python and C++ compiler. Windows users can easily install them by running the following command in PowerShell as administrator. For more information see https://github.com/felixrieseberg/windows-build-tools:
`sh
npm install --global --production windows-build-tools
`
The following are also needed:
- Windows SDK - only the "Desktop C++ Apps" components are needed to be installed
- Node.JS 10+
Debugging
The wiki contains instructions for debugging node-pty.
Security
All processes launched from node-pty will launch at the same permission level of the parent process. Take care particularly when using node-pty inside a server that's accessible on the internet. We recommend launching the pty inside a container to protect your host machine.
Thread Safety
Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.
Flow Control
Automatic flow control can be enabled by either providing handleFlowControl = true in the constructor options or setting it later on:
`js
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;
`
By default PAUSE and RESUME are XON/XOFF control codes (as shown above). To avoid conflicts in environments that use these control codes for different purposes the messages can be customized as flowControlPause: string and flowControlResume: string in the constructor options. PAUSE and RESUME are not passed to the underlying pseudoterminal if flow control is enabled.
Troubleshooting
$3
> Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d.
This happens when PowerShell is launched with no SystemRoot environment variable present.
$3
This error can occur due to anti-virus software intercepting winpty from creating a pty. To workaround this you can exclude this file from your anti-virus scanning node-pty\build\Release\winpty-agent.exe`