This project provides a React component that integrates the xterm.js terminal emulator library. It aims to offer a more up-to-date and flexible alternative to existing solutions(last commit Jul 8, 2022), with a focus on performance, code style, and additional functionality.

• On Replit: https://replit.com/@PabloLION/XTerm-React?v=1
• An example page, possibly with GitHub Pages. #TODO

To install the component, use npm, yarn, or pnpm:

npm install @pablo-lion/xterm-react # or yarn add @pablo-lion/xterm-react # or pnpm add @pablo-lion/xterm-react

Import the XTerm component and use it within your React application:

import React from "react"; import { XTerm } from "@pablo-lion/xterm-react"; export default function App() { return <XTerm />; }

The component's elementRef is a React.RefObject<HTMLDivElement | null>. Always guard against null before calling imperative APIs (e.g. ref.current?.focus()), especially during initial render.

For project guides and component references, start with the Documentation Index.

• See also official xterm.js documentation.

The XTerm component accepts several props to customize its behavior, including options for terminal options, addons for loading XTerm addons, and various event handlers like onData, onResize, and more. I'll add a full docs later.

• Personal Use: Tailored for my own personal requirements and projects.
• Updated Dependencies:
  • Utilizes the latest @xterm/xterm version than xterm to address issues with deprecated add-ons, such as the non-functional xterm-addon-fit in resizing terminals.
  • Newer react and typescript for peer dependencies.
• Code Style Improvements:
  • Adopting XTerm over Xterm for naming consistency.
  • Exposing terminal methods like .write(), .blur(), etc., directly from the XTerm class, enhancing developer experience and code readability.
  • Transitioning to @typescript-eslint for linting over tslint.
• Enhanced Functionality:
  • Integration of new event listeners from XTerm like onBell() and onWriteParsed().
  • Exposure of terminal methods such as .blur(), .focus(), and more for direct interaction.
  • Introduction of props for custom event handlers like attachCustomWheelEventHandler(), registerLinkProvider(), etc.
  • Implementation of a new link provider for registerLinkProvider().
• Performance Optimization: Removal of dynamic type checking to improve performance.
• Documentation Enhancements:
  • Updated documentation to align with @xterm/xterm, including new types like IEventListener.
  • Detailed comments for methods such as attachCustomWheelEventHandler, registerLinkProvider, registerCharacterJoiner, and others.
• Development and Testing: Adoption of vite for faster end-to-end testing, with plans to test add-ons thoroughly.

For development purposes, this project uses vite for a streamlined and efficient workflow.

Compatibility status: PASS 2 · FAIL 0 · XFAIL 0 · XPASS 0 — latest: version-compatibility-tests/MATRIX_SUMMARY.md

This library officially supports and is continuously tested against the following toolchain matrix via an in-repo consumer app (see docs/compatibility-testing.md):

• React: 18.3.x, 19.1.x (React 17 is out of scope)
• TypeScript: 5.2.2, 5.4.5, 5.9.3
• Linting / formatting families:
  • Biome: 2.0.0, 2.1.1, 2.2.4
  • ESLint: 8.57.0, 9.13.0 (paired with @eslint/js + @typescript-eslint/parser)
  • Prettier: 3.3.3, 3.6.2
• Runtime: Node 20 LTS by default; additional Node streams (node22, node24) can be exercised with --runtime flags (see the compatibility guide).

Latest matrix summary: version-compatibility-tests/MATRIX_SUMMARY.md

Run the matrix locally:

pnpm compat:matrix # run curated matrix and write logs pnpm compat:matrix:summary # generate Markdown summary for the latest run # Examples: `pnpm compat:matrix -- --linter biome` (Biome-only) or `--linter eslint-prettier --eslint 9.13.0 --prettier 3.6.2`

Migration: legacy scripts such as pnpm run test:versions, pnpm run test:react, pnpm run test:eslint, and pnpm run test:biome have been removed. Use the filtered pnpm run compat:matrix commands above instead.

For a quick smoke on the latest combo:

pnpm compat:consumer:build-latest

The release workflow is automated by the scripts/prepare-publish.sh helper. Run the script with either a semantic version bump (--bump major|minor|patch) or an explicit --version value to prepare and publish a release.

Contributions are welcome! Please feel free to submit pull requests or open issues to discuss potential improvements or features.

• For dev, pnpm is recommended.
• Capture feature plans and retrospectives under docs/dev-logs/ using the provided template. Start filenames with YYYYMMDD- so logs sort chronologically, and include an Atomic Commit Breakdown section before implementation begins.

• XTerm.js:
• React
• robert-harbison/xterm-for-react

I found many many packages after finishing this project... I felt like I wasted 2 days but it seems to me that mine has the most up-to-date xterm.js version and the most features added to xterm-for-react.

• xterm-react
• react-xterm
• react-xtermjs
• oas-xterm-for-react18
• @devt8/xterm-for-react
• xterm-for-react-fixed

I can wrap up this to a useXterm hook like the example below, but I think it's better to just keep it as a component. If you want to use it as a hook, make an issue or shoot me a message. Definition of useXterm hook can be like this:

import { useRef, useEffect } from "react"; import XTerm from "./XTerm"; const useXTerm = () => { const xtermRef = useRef(); useEffect(() => { if (xtermRef.current) { xtermRef.current.write = xtermRef.current.write.bind(xtermRef.current); xtermRef.current.focus = xtermRef.current.focus.bind(xtermRef.current); xtermRef.current.blur = xtermRef.current.blur.bind(xtermRef.current); } }, []); return { setRef: xtermRef, write: (data) => xtermRef.current.write(data), focus: () => xtermRef.current.focus(), blur: () => xtermRef.current.blur(), }; }; export default useXTerm;

Then, in use it is like this

import React, { useEffect } from "react"; import XTerm from "./XTerm"; import useXTerm from "./useXTerm"; const App = () => { const { setRef, write, focus, blur } = useXTerm<XTerm>(null); useEffect(() => { write("Hello, XTerm!\n"); focus(); }, []); return ( <div> <h1>Using XTerm with Custom Hook</h1> <XTerm ref={setRef} /> <button onClick={() => write("Button clicked!\n")}> Write to Terminal </button> <button onClick={focus}>Focus Terminal</button> <button onClick={blur}>Blur Terminal</button> </div> ); }; export default App;

This project is licensed under the MIT License. See the LICENSE file for more details.