Skip to content

Commit e5f6964

Browse files
kylecarbskylecarbs
committed
Update the README
1 parent 4ef099b commit e5f6964

File tree

1 file changed

+40
-99
lines changed

1 file changed

+40
-99
lines changed

‎README.md‎

Lines changed: 40 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,82 @@
11
# ghostty-web
22

3-
![ghostty](https://github.com/user-attachments/assets/aceee7eb-d57b-4d89-ac3d-ee1885d0187a)
3+
[![NPM Version](https://img.shields.io/npm/v/ghostty-web)](https://npmjs.com/package/ghostty-web) [![NPM Downloads](https://img.shields.io/npm/dw/ghostty-web)](https://npmjs.com/package/ghostty-web) [![license](https://img.shields.io/github/license/coder/ghostty-web)](./LICENSE)
44

5-
`ghostty-web` is a web terminal developed for [mux](https://github.com/coder/mux) that leverages
6-
[Ghostty's](https://github.com/ghostty-org/ghostty)
7-
terminal emulation core via WebAssembly. Because it leans on Ghostty to handle the complexity of terminal
8-
emulation, `ghostty-web` can deliver fast, robust terminal emulation in the browser. The intent is
9-
for this project to become a drop-in replacement for xterm.js. Under heavy development, no compatibility guarantees yet.
5+
[Ghostty](https://github.com/ghostty-org/ghostty) for the web with [xterm.js](https://github.com/xtermjs/xterm.js) API compatibility — giving you a proper VT100 implementation in the browser, not a JavaScript approximation of one.
106

11-
## Live Demo
7+
- Migrate from xterm by changing your import: `@xterm/xterm` → `ghostty-web`
8+
- WASM-compiled parser from Ghostty—the same code that runs the native app
9+
- Zero runtime dependencies, ~400KB WASM bundle
1210

13-
Try ghostty-web yourself with:
11+
## Try It
1412

1513
```bash
1614
npx @ghostty-web/demo@next
1715
```
1816

19-
This starts a local demo server with a real shell session. The demo server works best when run from Linux, but you can also try
20-
it on macOS. Windows is not supported (yet).
17+
This starts a local HTTP server with a real shell on `http://localhost:8080`. Works best on Linux and macOS.
2118

22-
<details>
23-
<summary>Development setup (building from source)</summary>
19+
![ghostty](https://github.com/user-attachments/assets/aceee7eb-d57b-4d89-ac3d-ee1885d0187a)
2420

25-
> Requires Zig and Bun, see [Development](#development)
21+
## Comparison with xterm.js
2622

27-
```bash
28-
git clone https://github.com/coder/ghostty-web
29-
cd ghostty-web
30-
bun install
31-
bun run build # Builds the WASM module and library
32-
bun run demo:dev # http://localhost:8000/demo/
33-
```
23+
xterm.js is everywhere—VS Code, Hyper, countless web terminals. But it has fundamental issues:
3424

35-
</details>
25+
| Issue | xterm.js | ghostty-web |
26+
| ---------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
27+
| **RTL languages** | [Broken since 2017](https://github.com/xtermjs/xterm.js/issues/701) | ✓ Works |
28+
| **Complex scripts** (Devanagari, Arabic) | Rendering issues | ✓ Proper grapheme handling |
29+
| **XTPUSHSGR/XTPOPSGR** | [Not supported](https://github.com/xtermjs/xterm.js/issues/2570) | ✓ Full support |
3630

37-
## Getting Started
31+
xterm.js reimplements terminal emulation in JavaScript. Every escape sequence, every edge case, every Unicode quirk—all hand-coded. Ghostty's emulator is the same battle-tested code that runs the native Ghostty app.
3832

39-
Install the module via npm
33+
## Installation
4034

4135
```bash
4236
npm install ghostty-web
4337
```
4438

45-
After install, using `ghostty-web` is as simple as
46-
47-
```html
48-
<!doctype html>
49-
<html>
50-
<body>
51-
<div id="terminal"></div>
52-
<script type="module">
53-
import { init, Terminal } from 'ghostty-web';
54-
55-
await init();
56-
const term = new Terminal();
57-
term.open(document.getElementById('terminal'));
58-
term.write('Hello from \x1B[1;3;31mghostty-web\x1B[0m $ ');
59-
</script>
60-
</body>
61-
</html>
62-
```
63-
64-
## Features
65-
66-
`ghostty-web` compiles Ghostty's core terminal emulation engine (parser, state
67-
machine, and screen buffer) to WebAssembly, providing:
68-
69-
**Core Terminal:**
70-
71-
- Full VT100/ANSI escape sequence support
72-
- True color (24-bit RGB) + 256 color + 16 ANSI colors
73-
- Text styles: bold, italic, underline, strikethrough, dim, reverse
74-
- Alternate screen buffer (for vim, htop, less, etc.)
75-
- Scrollback buffer with mouse wheel support
76-
77-
**Input & Interaction:**
78-
79-
- Text selection and clipboard integration
80-
- Mouse tracking modes
81-
- Custom key/wheel event handlers
82-
83-
**API & Integration:**
84-
85-
- xterm.js-compatible API (drop-in replacement for many use cases)
86-
- FitAddon for responsive terminal sizing
87-
- Event system (onData, onResize, onBell, onScroll, etc.)
88-
89-
**Performance:**
39+
## Usage
9040

91-
- Canvas-based rendering at 60 FPS
92-
- Zero runtime dependencies (just ghostty-web + bundled WASM)
93-
- Parser/state machine from Ghostty
41+
ghostty-web aims to be API-compatible with the xterm.js API.
9442

95-
## Usage Examples
43+
```javascript
44+
import { init, Terminal } from 'ghostty-web';
9645

97-
### Basic Terminal
98-
99-
```typescript
100-
import { init, Terminal, FitAddon } from 'ghostty-web';
101-
102-
// Initialize WASM (call once at app startup)
10346
await init();
10447

10548
const term = new Terminal({
106-
cursorBlink: true,
10749
fontSize: 14,
10850
theme: {
109-
background: '#1e1e1e',
110-
foreground: '#d4d4d4',
51+
background: '#1a1b26',
52+
foreground: '#a9b1d6',
11153
},
11254
});
11355

114-
const fitAddon = new FitAddon();
115-
term.loadAddon(fitAddon);
116-
11756
term.open(document.getElementById('terminal'));
118-
fitAddon.fit();
119-
120-
// Handle user input
121-
term.onData((data) => {
122-
// Send to backend/PTY
123-
console.log('User typed:', data);
124-
});
57+
term.onData((data) => websocket.send(data));
58+
websocket.onmessage = (e) => term.write(e.data);
12559
```
12660

127-
## Development
128-
129-
### Prerequisites
61+
For a comprehensive client <-> server example, refer to the [demo](./demo/index.html#L141).
13062

131-
- [bun](https://bun.com/docs/installation)
132-
- [zig](https://ziglang.org/download/)
63+
## Development
13364

134-
### Building WASM
65+
ghostty-web builds from Ghostty's source with a [patch](./patches/ghostty-wasm-api.patch) to expose additional
66+
functionality.
13567

136-
`ghostty-web` builds a custom WASM binary from Ghostty's source with a patch to expose additional
137-
functionality
68+
> Requires Zig and Bun.
13869
13970
```bash
14071
bun run build
14172
```
73+
74+
Mitchell Hashimoto (author of Ghostty) has [been working](https://mitchellh.com/writing/libghostty-is-coming) on `libghostty` which makes this all possible. The patches are very minimal thanks to the work the Ghostty team has done, and we expect them to get smaller.
75+
76+
This library will eventually consume a native Ghostty WASM distribution once available, and will continue to provide an xterm.js compatible API.
77+
78+
At Coder we're big fans of Ghostty, so kudos to that team for all the amazing work.
79+
80+
## License
81+
82+
[MIT](./LICENSE)

0 commit comments

Comments
 (0)