Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pablolion/xterm-react

React component for xterm.js terminal integration
https://github.com/pablolion/xterm-react

component console react reactjs xterm xterm-js xtermjs

Last synced: 2 months ago
JSON representation

React component for xterm.js terminal integration

Awesome Lists containing this project

README 

        
## XTerm for React



This project provides a React component that integrates the [xterm.js](https://xtermjs.org/) terminal emulator library. It aims to offer a more up-to-date and flexible alternative to [existing solutions](https://github.com/robert-harbison/xterm-for-react)(last commit Jul 8, 2022), with a focus on performance, code style, and additional functionality.



### Live Example



- On Replit: 

- A example page with mb github pages. #TODO



## Usage



## Installation



To install the component, use package manager like `npm`, `yarn` or `pnpm`:



```sh

npm install xterm-react

# or

yarn add xterm-react

# or

pnpm add xterm-react

```



### Code Example



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



```jsx

import React from "react";

import { XTerm } from "@pablo-lion/xterm-react";



export default function App() {

  return ;

}

```



### Docs



For the documentation of the `XTerm` component, check [XTerm-React Docs](./docs.md).



- See also [official xterm.js documentation](https://xtermjs.org/docs/api/terminal/).



### Props



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.



## Motivations



- **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.



## Development



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



## Contributing



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



- For dev, `pnpm` is recommended.



### Credits



- [XTerm.js:](https://xtermjs.org/)

- [React](https://reactjs.org/)

- [robert-harbison/xterm-for-react](https://github.com/robert-harbison/xterm-for-react)



#### Honorable mentions



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](https://www.npmjs.com/package/xterm-react)

- [react-xterm](https://www.npmjs.com/package/react-xterm)

- [react-xtermjs](https://www.npmjs.com/package/react-xtermjs)

- [oas-xterm-for-react18](https://www.npmjs.com/package/oas-xterm-for-react18)

- [@devt8/xterm-for-react](https://www.npmjs.com/package/@devt8/xterm-for-react)

- [xterm-for-react-fixed](https://www.npmjs.com/package/xterm-for-react-fixed)



### Decisions



#### Do we need a `useXterm` hook?



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:



```tsx

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



```tsx

import React, { useEffect } from "react";

import XTerm from "./XTerm";

import useXTerm from "./useXTerm";



const App = () => {

  const { setRef, write, focus, blur } = useXTerm(null);



  useEffect(() => {

    write("Hello, XTerm!\n");

    focus();

  }, []);



  return (

    


      
Using XTerm with Custom Hook


      

       write("Button clicked!\n")}>

        Write to Terminal

      

      Focus Terminal

      Blur Terminal

    


  );

};



export default App;

```



## License



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