{"id":17963760,"url":"https://github.com/pablolion/xterm-react","last_synced_at":"2026-03-06T07:03:08.881Z","repository":{"id":242755348,"uuid":"809930470","full_name":"PabloLION/xterm-react","owner":"PabloLION","description":"React component for xterm.js terminal integration","archived":false,"fork":false,"pushed_at":"2025-10-15T19:33:34.000Z","size":908,"stargazers_count":15,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-16T20:41:04.758Z","etag":null,"topics":["component","console","react","reactjs","xterm","xterm-js","xtermjs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@pablo-lion/xterm-react","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PabloLION.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-06-03T18:14:22.000Z","updated_at":"2025-10-09T11:46:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"9483e2a3-e7d6-4113-91ad-53baadc78c21","html_url":"https://github.com/PabloLION/xterm-react","commit_stats":null,"previous_names":["pablolion/xterm-react"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PabloLION/xterm-react","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PabloLION%2Fxterm-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PabloLION%2Fxterm-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PabloLION%2Fxterm-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PabloLION%2Fxterm-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PabloLION","download_url":"https://codeload.github.com/PabloLION/xterm-react/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PabloLION%2Fxterm-react/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30164901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T04:43:31.446Z","status":"ssl_error","status_checked_at":"2026-03-06T04:40:30.133Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","console","react","reactjs","xterm","xterm-js","xtermjs"],"created_at":"2024-10-29T11:45:05.484Z","updated_at":"2026-03-06T07:03:08.862Z","avatar_url":"https://github.com/PabloLION.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XTerm React\n\nThis 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.\n\n## Live Example\n\n- On Replit: \u003chttps://replit.com/@PabloLION/XTerm-React?v=1\u003e\n- An example page, possibly with GitHub Pages. #TODO\n\n## Usage\n\n## Installation\n\nTo install the component, use `npm`, `yarn`, or `pnpm`:\n\n```sh\nnpm install @pablo-lion/xterm-react\n# or\nyarn add @pablo-lion/xterm-react\n# or\npnpm add @pablo-lion/xterm-react\n```\n\n### Code Example\n\nImport the `XTerm` component and use it within your React application:\n\n```jsx\nimport React from \"react\";\nimport { XTerm } from \"@pablo-lion/xterm-react\";\n\nexport default function App() {\n  return \u003cXTerm /\u003e;\n}\n```\n\n\u003e The component's `elementRef` is a `React.RefObject\u003cHTMLDivElement | null\u003e`.\n\u003e Always guard against `null` before calling imperative APIs (e.g.\n\u003e `ref.current?.focus()`), especially during initial render.\n\n### Docs\n\nFor project guides and component references, start with the [Documentation Index](./docs/index.md).\n\n- See also [official xterm.js documentation](https://xtermjs.org/docs/api/terminal/).\n\n### Props\n\nThe `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.\nI'll add a full docs later.\n\n## Motivations\n\n- **Personal Use**: Tailored for my own personal requirements and projects.\n- **Updated Dependencies**:\n  - 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.\n  - Newer `react` and `typescript` for peer dependencies.\n- **Code Style Improvements**:\n  - Adopting `XTerm` over `Xterm` for naming consistency.\n  - Exposing terminal methods like `.write()`, `.blur()`, etc., directly from the XTerm class, enhancing developer experience and code readability.\n  - Transitioning to `@typescript-eslint` for linting over `tslint`.\n- **Enhanced Functionality**:\n  - Integration of new event listeners from XTerm like `onBell()` and `onWriteParsed()`.\n  - Exposure of terminal methods such as `.blur()`, `.focus()`, and more for direct interaction.\n  - Introduction of props for custom event handlers like `attachCustomWheelEventHandler()`, `registerLinkProvider()`, etc.\n  - Implementation of a new link provider for `registerLinkProvider()`.\n- **Performance Optimization**: Removal of dynamic type checking to improve performance.\n- **Documentation Enhancements**:\n  - Updated documentation to align with `@xterm/xterm`, including new types like `IEventListener`.\n  - Detailed comments for methods such as `attachCustomWheelEventHandler`, `registerLinkProvider`, `registerCharacterJoiner`, and others.\n- **Development and Testing**: Adoption of `vite` for faster end-to-end testing, with plans to test add-ons thoroughly.\n\n## Development\n\nFor development purposes, this project uses `vite` for a streamlined and efficient workflow.\n\n## Compatibility\n\n\u003c!-- compat-matrix-badge:begin --\u003e\nCompatibility status: PASS 1 · FAIL 0 · XFAIL 0 · XPASS 0 — latest: version-compatibility-tests/MATRIX_SUMMARY.md\n\u003c!-- compat-matrix-badge:end --\u003e\n\nThis library officially supports and is continuously tested against the following toolchain matrix via an in-repo consumer app (see docs/compatibility-testing.md):\n\n- React: 18.3.x, 19.1.x (React 17 is out of scope)\n- TypeScript: 5.2.2, 5.4.5, 5.9.3\n- Linting / formatting families:\n  - Biome: 2.0.0, 2.1.1, 2.2.4\n  - ESLint: 8.57.0, 9.13.0 (paired with `@eslint/js` + `@typescript-eslint/parser`)\n  - Prettier: 3.3.3, 3.6.2\n- Runtime: Node 20 LTS by default; additional Node streams (`node22`, `node24`) can be exercised with `--runtime` flags (see the compatibility guide).\n\nLatest matrix summary: `version-compatibility-tests/MATRIX_SUMMARY.md`\n\nRun the matrix locally:\n\n```sh\npnpm compat:matrix         # run curated matrix and write logs\npnpm compat:matrix:summary # generate Markdown summary for the latest run\n# Examples: `pnpm compat:matrix -- --linter biome` (Biome-only) or `--linter eslint-prettier --eslint 9.13.0 --prettier 3.6.2`\n```\n\n\u003e **Compatibility tooling note:** the in-repo runner and consumer scripts are authored in TypeScript and compiled as native ESM via `module: \"NodeNext\"`. No `.mts` files are used; the build pipeline guarantees ESM output while keeping a single `.ts` extension across the codebase.\n\nMigration: legacy scripts such as `pnpm run test:versions`, `pnpm run test:react`,\n`pnpm run test:eslint`, and `pnpm run test:biome` have been removed. Use the\nfiltered `pnpm run compat:matrix` commands above instead.\n\nFor a quick smoke on the latest combo:\n\n```sh\npnpm compat:consumer:build-latest\n```\n\n## Release\n\nThe release workflow is automated by the [`scripts/prepare-publish.sh`](scripts/prepare-publish.sh) helper. Run the script with\neither a semantic version bump (`--bump major|minor|patch`) or an explicit `--version` value to prepare and publish a release.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues to discuss potential improvements or features.\n\n- For dev, `pnpm` is recommended.\n- 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.\n\n### Credits\n\n- [XTerm.js:](https://xtermjs.org/)\n- [React](https://reactjs.org/)\n- [robert-harbison/xterm-for-react](https://github.com/robert-harbison/xterm-for-react)\n\n#### Honorable mentions\n\nI 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`.\n\n- [xterm-react](https://www.npmjs.com/package/xterm-react)\n- [react-xterm](https://www.npmjs.com/package/react-xterm)\n- [react-xtermjs](https://www.npmjs.com/package/react-xtermjs)\n- [oas-xterm-for-react18](https://www.npmjs.com/package/oas-xterm-for-react18)\n- [@devt8/xterm-for-react](https://www.npmjs.com/package/@devt8/xterm-for-react)\n- [xterm-for-react-fixed](https://www.npmjs.com/package/xterm-for-react-fixed)\n\n### Decisions\n\n#### Do we need a `useXterm` hook?\n\nI 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.\nDefinition of `useXterm` hook can be like this:\n\n```tsx\nimport { useRef, useEffect } from \"react\";\nimport XTerm from \"./XTerm\";\n\nconst useXTerm = () =\u003e {\n  const xtermRef = useRef();\n\n  useEffect(() =\u003e {\n    if (xtermRef.current) {\n      xtermRef.current.write = xtermRef.current.write.bind(xtermRef.current);\n      xtermRef.current.focus = xtermRef.current.focus.bind(xtermRef.current);\n      xtermRef.current.blur = xtermRef.current.blur.bind(xtermRef.current);\n    }\n  }, []);\n\n  return {\n    setRef: xtermRef,\n    write: (data) =\u003e xtermRef.current.write(data),\n    focus: () =\u003e xtermRef.current.focus(),\n    blur: () =\u003e xtermRef.current.blur(),\n  };\n};\n\nexport default useXTerm;\n```\n\nThen, in use it is like this\n\n```tsx\nimport React, { useEffect } from \"react\";\nimport XTerm from \"./XTerm\";\nimport useXTerm from \"./useXTerm\";\n\nconst App = () =\u003e {\n  const { setRef, write, focus, blur } = useXTerm\u003cXTerm\u003e(null);\n\n  useEffect(() =\u003e {\n    write(\"Hello, XTerm!\\n\");\n    focus();\n  }, []);\n\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eUsing XTerm with Custom Hook\u003c/h1\u003e\n      \u003cXTerm ref={setRef} /\u003e\n      \u003cbutton onClick={() =\u003e write(\"Button clicked!\\n\")}\u003e\n        Write to Terminal\n      \u003c/button\u003e\n      \u003cbutton onClick={focus}\u003eFocus Terminal\u003c/button\u003e\n      \u003cbutton onClick={blur}\u003eBlur Terminal\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default App;\n```\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablolion%2Fxterm-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpablolion%2Fxterm-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablolion%2Fxterm-react/lists"}