react-ttyd
Version:
A React component for integrating ttyd web terminal with Xterm.js, supporting WebGL rendering and WebSocket connections
294 lines (227 loc) • 8.77 kB
Markdown
# react-ttyd
A React component for integrating [ttyd](https://github.com/tsl0922/ttyd) web terminal with [Xterm.js](https://xtermjs.org/), supporting WebGL rendering and WebSocket connections.
[](https://www.npmjs.com/package/react-ttyd)
[](https://www.npmjs.com/package/react-ttyd)
[](https://opensource.org/licenses/MIT)
## Features
- 🚀 WebGL, Canvas, and DOM rendering support
- 🔌 WebSocket integration for ttyd connections
- 📋 Clipboard support (copy/paste)
- 🔗 Clickable links
- 🖼️ Image support in terminal
- 📱 Responsive terminal with fit addon
- ⚡ High performance with WebGL renderer
- 🎨 Customizable terminal options
- 🔒 Authentication support (basic auth and token-based)
- 🌐 Unicode support
## Installation
```bash
npm install react-ttyd
```
or
```bash
yarn add react-ttyd
```
## Quick Start
First, make sure you have a ttyd server running. Check [ttyd](https://github.com/tsl0922/ttyd) for installation instructions.
```bash
# macOS
brew install ttyd
# Start ttyd
ttyd --writable bash
```
Then use the component in your React application:
```tsx
import { Ttyd } from 'react-ttyd';
function App() {
return (
<Ttyd
wsUrl="ws://localhost:7681/ws"
clientOptions={{
rendererType: 'webgl'
}}
termOptions={{
fontSize: 14,
}}
/>
);
}
```
### With Basic Authentication
If your ttyd server requires authentication, you can provide credentials:
```bash
# Start ttyd with basic auth
ttyd --writable --credential testuser:testpw bash
```
```tsx
<Ttyd
wsUrl="ws://localhost:7681/ws"
authToken={btoa('testuser:testpw')}
clientOptions={{
rendererType: 'webgl'
}}
/>
```
### Expose the ttyd port
```bash
# Install ngrok
brew install ngrok
# Run ngrok
ngrok http 7681
```
## API Reference
### Ttyd Component Props
| Prop | Type | Description | Default |
| ------------------- | ----------------------------- | --------------------------------------------- | ------------ |
| `wsUrl` | `string` | WebSocket URL of ttyd server | **Required** |
| `tokenUrl` | `string` | URL to fetch auth token (if using token auth) | - |
| `authToken` | `string` | Base64 encoded credentials for basic auth | - |
| `clientOptions` | `ClientOptions` | Terminal client options | `{}` |
| `termOptions` | `ITerminalOptions` | Xterm.js terminal options | `{}` |
| `onConnectionOpen` | `(event: Event) => void` | WebSocket open callback | - |
| `onConnectionClose` | `(event: CloseEvent) => void` | WebSocket close callback | - |
| `onConnectionError` | `(event: Event) => void` | WebSocket error callback | - |
| `onData` | `(data: string) => void` | Terminal data callback | - |
| `id` | `string` | Terminal container element ID | - |
| `className` | `string` | Terminal container CSS class | - |
| `addons` | `TerminalAddon[]` | Additional Xterm.js addons | - |
### ClientOptions
| Option | Type | Description | Default |
| ---------------- | ------------------------------ | -------------------------- | ------------- |
| `rendererType` | `'webgl' \| 'canvas' \| 'dom'` | Renderer type | `'webgl'` |
| `enableZmodem` | `boolean` | Enable Zmodem support | `false` |
| `enableTrzsz` | `boolean` | Enable trzsz support | `false` |
| `enableSixel` | `boolean` | Enable Sixel support | `false` |
| `isWindows` | `boolean` | Windows compatibility mode | Auto-detected |
| `unicodeVersion` | `'6' \| '11'` | Unicode version | `'11'` |
### Terminal Options
The `termOptions` prop accepts all [Xterm.js terminal options](https://xtermjs.org/docs/api/terminal/interfaces/iterminaloptions/).
Common options:
```tsx
<Ttyd
wsUrl="ws://localhost:7681/ws"
termOptions={{
fontSize: 14,
fontFamily: 'Menlo, Monaco, "Courier New", monospace',
theme: {
background: '#1e1e1e',
foreground: '#ffffff'
},
cursorBlink: true,
cursorStyle: 'block'
}}
/>
```
## Advanced Usage 🚧 Under Development
This section is currently under development. More advanced features and examples will be added soon!
```tsx
<Ttyd
wsUrl="ws://localhost:7681/ws"
authToken={btoa('testuser:testpw')}
/>
```
```tsx
<Ttyd
wsUrl="ws://localhost:7681/ws"
authToken="your-auth-token"
/>
```
### Custom Addons
```tsx
import { Terminal } from '@xterm/xterm';
import { MyCustomAddon } from './MyCustomAddon';
<Ttyd
wsUrl="ws://localhost:7681/ws"
addons={[new MyCustomAddon()]}
/>
```
### Event Handlers
```tsx
<Ttyd
wsUrl="ws://localhost:7681/ws"
onConnectionOpen={(event) => {
console.log('Connected to ttyd server');
}}
onConnectionClose={(event) => {
console.log('Disconnected from ttyd server');
}}
onConnectionError={(event) => {
console.error('Connection error:', event);
}}
onData={(data) => {
console.log('Terminal output:', data);
}}
/>
```
## Examples
Check out the [example](https://github.com/tantara/react-ttyd/tree/main/example) directory for a complete working example.
To run the example:
```bash
# Clone the repository
git clone https://github.com/tantara/react-ttyd.git
cd react-ttyd
# Install dependencies
npm install
# Build the library
npm run build
# Start ttyd server (in another terminal)
ttyd --writable bash
# Run the example
cd example/nextjs # or cd example/vite
npm install
npm run dev
```
## Browser Support
- Chrome/Edge (recommended for WebGL support)
- Firefox
- Safari
- Mobile browsers (with touch support)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [ttyd](https://github.com/tsl0922/ttyd) - Share your terminal over the web
- [Xterm.js](https://xtermjs.org/) - Terminal for the web
- [@homebridge/plugin-ui-utils](https://github.com/homebridge/homebridge-config-ui-x) - Inspiration for the terminal implementation
## TODO
The following features from the original ttyd/html implementation are not yet ported to react-ttyd:
### Core Features
- [ ] Token-based authentication (`tokenUrl` and `refreshToken()`)
- [ ] Command protocol support (SET_PREFERENCES command)
- [ ] URL query parameter parsing for options
- [ ] Flow control (pause/resume commands)
- [ ] Reconnection mechanism with overlay
- [ ] Window unload warning when terminal is active
- [ ] Title management (titleFixed option)
- [ ] `closeOnDisconnect` behavior
### File Transfer & Advanced Features
- [ ] Zmodem support (`enableZmodem` option)
- [ ] Trzsz support (`enableTrzsz` option)
- [ ] Sixel graphics support (`enableSixel` option)
- [ ] Modal for file uploads
- [ ] `sendFile()` functionality
- [ ] Drag and drop file support
### UI/UX Features
- [ ] Resize overlay (`disableResizeOverlay` option)
- [ ] Leave alert (`disableLeaveAlert` option)
- [ ] Connection status overlay
- [ ] Reconnection overlay with "Press Enter to Reconnect"
- [ ] Selection copy overlay (scissors icon)
### Terminal Management
- [ ] Global `window.term` object with `fit()` method
- [ ] Dispose pattern for proper cleanup
- [ ] Binary data handling
- [ ] Proper WebSocket command protocol
### Configuration
- [ ] Server-side preference updates
- [ ] Windows-specific options (`isWindows`)
- [ ] trzszDragInitTimeout option
## Related Projects
- [ttyd](https://github.com/tsl0922/ttyd) - The backend terminal server
- [xterm.js](https://github.com/xtermjs/xterm.js) - The terminal emulator used in this component