Contributing

Xterm.js is maintained by several core team members, but we would love to receive contributions from everyone!

To contribute either code, documentation or issues to xterm.js please read the Contributing document beforehand. All you need to contribute is an editor that supports JavaScript/TypeScript, a browser. You will need Node.js installed locally to get all the features working in the demo.

Running the Demo

The xterm.js repo contains a barebones demo implementation, designed for the development and evaluation of the library only. Note that exposing the demo to the public as is would introduce security risks for the host.

Below you can find instructions on how to run the demo on different platforms. We recommend using Yarn to make sure the dependencies are installed correctly but npm should work most of the time. You will also need variable dependencies for the node-pty dependency like python and make, see (detailed instructions here](https://github.com/Microsoft/node-pty#dependencies).

SourceLair

SourceLair will run the demo and builder in parallel automatically. Just make sure to choose the "Node.js" project type, when cloning the xterm.js repo (or just use this shortcut; https://lair.io/xtermjs/xtermjs).

Then open your project's Public URL to access the demo.

Docker

First, make sure you have Docker Engine 1.13.0 (or newer) and Docker Compose 1.10.0 (or newer).

Xterm.js provides a pre-built Docker image to help run the demo easily (Git tags are built as tagged Docker images too).

To run the just demo (with no editing access). run the following command in your terminal:

docker run -p 3000:3000 xtermjs/xterm.js

Then open http://0.0.0.0:3000 in a web browser to access the demo.

To run the demo and builder in parallel, run the following command in your terminal:

docker-compose up

Then open http://0.0.0.0:3000 in a web browser to access the demo. If you prefer a different port than 3000 to access the xterm.js demo, then set the XTERMJS_PORT environment variable to the desired port.

Foreman (or other Procfile runner)

First, be sure that a C++ compiler such as GCC-C++ or Clang is installed, then run the following commands in your terminal:

yarn
foreman start  # Replace foreman with "honcho", "forego" etc. depending on your runner

Then open http://0.0.0.0:3000 in a web browser to access the demo.

Linux or macOS

First, be sure that a C++ compiler such as GCC-C++ or Clang is installed, then run the following commands in your terminal:

yarn
yarn start      # Run this in its own terminal
yarn run watch  # Run this in its own terminal

Then open http://0.0.0.0:3000 in a web browser to access the demo.

Windows

First, ensure node-gyp is installed and configured correctly, then run the following commands in your terminal:

yarn
yarn start      # Run this in its own terminal
yarn run watch  # Run this in its own terminal

Then open http://127.0.0.1:3000 in a web browser to access the demo.

Note: Do not use ConEmu, as it seems to break the demo for some reason.

Testing

Tests are run using the following npm scripts:

• yarn test: This will run both unit tests and the linter
• yarn test-suite <file>: This will run all tests within a particular file, <file> is the test file name excluding the extension (eg. "Linkifier.test")
• yarn test-debug: This will run unit tests with --inspect-brk, this can then be automatically debugged using VS Code auto attach or manually attached to by a debugger
• yarn test-coverage: This will run all unit tests and produce a coverage report
• yarn lint: This will run the linter only

Enabling debug mode

Xterm.js has a debug mode that allows you to view what's being evaluated by the terminal. To enable this mode, run the demo and execute the following in the console:

term._core.debug = true

Any data sent to the terminal should be output in the console.

Third party dependencies

We prefer to not include any non-dev third party dependencies in order to keep our code minimal, performant and secure. If you plan on adding a dependency on a third party library it's a good idea to discuss the need in an issue with the maintainers first.