React VNC Library 🖥️


A modern, lightweight VNC client library for React applications with working VNC authentication!

✨ Key Features

- 🎯 Working VNC Authentication - RFC 6143 compliant with proper DES implementation
- ⚡ WebSocket Support - Real-time VNC connections over WebSocket
- 🔒 Secure - Supports both VNC authentication and "None" security types
- 🌐 Hetzner Compatible - Tested with Hetzner VNC web console
- 📱 Responsive - Auto-scaling and touch/mouse input support
- 🎨 Modern React - Hooks-based API with TypeScript support
- 🔧 Flexible - Works with any VNC server (TightVNC, RealVNC, etc.)

🚀 Quick Start

$3

``bash
npm install react-vnc-lib


or

`tsx
import React from 'react';
import { useVNC } from 'react-vnc-lib';

function VNCViewer() {
const { connect, disconnect, state, canvasRef } = useVNC({
url: 'wss://your-vnc-server.com/websockify',
password: 'your-vnc-password', // Now works properly!
viewOnly: false,
scale: 1.0,
debug: true
});

return (


export default VNCViewer;
`

🎯 Authentication Status: FIXED ✅

This library now has properly working VNC authentication based on RFC 6143 compliance! Here's what was fixed:

$3

`tsx
interface VNCClientOptions {
url: string; // WebSocket URL (ws:// or wss://)
username?: string; // Optional username (for future auth types)
password?: string; // VNC password (now works properly!)
viewOnly?: boolean; // Read-only mode (default: false)
quality?: number; // Image quality 1-10 (default: 6)
compression?: number; // Compression level 1-10 (default: 2)
autoResize?: boolean; // Auto resize canvas (default: true)
scale?: number; // Display scale factor (default: 1.0)
timeout?: number; // Connection timeout ms (default: 10000)
debug?: boolean; // Enable debug logging (default: false)
}
`

🔧 Advanced Usage

$3

`tsx
import { VNCClient } from 'react-vnc-lib';

// Direct VNC client usage
const client = new VNCClient({
url: 'wss://vnc.example.com/websockify',
password: 'secret123',
debug: true
});

// Event handling
client.on('connected', () => console.log('VNC Connected!'));
client.on('disconnected', () => console.log('VNC Disconnected'));
client.on('error', (event) => console.error('VNC Error:', event.data.message));

// Connect
await client.connect();

// Send input
client.sendKeyEvent({ key: 'Enter', down: true, code: 'Enter' });
client.sendPointerEvent({ x: 100, y: 100, buttons: 1 });

// Disconnect
client.disconnect();
`

$3

`tsx
function VNCViewer() {
const { connect, state } = useVNC({
url: 'wss://vnc.example.com/websockify',
password: 'secret'
});

const handleConnect = async () => {
try {
await connect();
} catch (error) {
console.error('Connection failed:', error.message);
// Handle specific error types
if (error.message.includes('Authentication failed')) {
alert('Invalid password');
} else if (error.message.includes('Connection timeout')) {
alert('Server not reachable');
}
}
};

return (


1. Authentication Fails
`
Enable debug mode and check console for challenge/response hex values
Ensure password is correct and server supports VNC Authentication
`

2. Connection Refused
`
Check WebSocket URL format (ws:// or wss://)
Verify server is running and accessible
Check for CORS issues in browser
`

3. WebSocket Close Codes
`
1006: Connection lost unexpectedly
1003: Server rejected connection due to invalid data
1002: Protocol error
`

$3

Enable debug logging to see detailed connection information:

`tsx
const { connect } = useVNC({
url: 'wss://vnc.example.com/websockify',
password: 'secret',
debug: true // Enables detailed console logging
});
`

🏗️ Architecture

$3

`bash


With npm

`bash
npm install react react-dom
`

Quick Start

$3

`tsx
import React from 'react';
import { VNCViewer } from 'react-vnc-lib';

function App() {
return (


export default App;
`

$3

`tsx
import React from 'react';
import { useVNC } from 'react-vnc-lib';

function CustomVNCViewer() {
const {
state,
connect,
disconnect,
canvasRef,
error,
loading
} = useVNC({
url: 'ws://localhost:6080',
autoConnect: true,
debug: true
});

return (


`javascript
import { VNCClient } from 'react-vnc-lib';

const client = new VNCClient({
url: 'ws://localhost:6080',
username: 'user',
password: 'password',
debug: true
});

// Set up event listeners
client.on('connected', () => {
console.log('Connected to VNC server');
});

client.on('error', (event) => {
console.error('VNC Error:', event.data.message);
});

client.on('framebuffer-update', (event) => {
console.log('Received framebuffer update');
// Handle framebuffer data
});

// Connect
await client.connect();

// Send keyboard input
client.sendKeyEvent({
key: 'a',
code: 'KeyA',
down: true
});

// Send mouse input
client.sendPointerEvent({
x: 100,
y: 100,
buttons: 1
});

// Disconnect
client.disconnect();
`

API Reference

$3

Main VNC client class for establishing connections and handling protocol communication.

#### Constructor

`typescript
new VNCClient(options: VNCClientOptions)
`

#### Options

`typescript
interface VNCClientOptions {
url: string; // WebSocket URL to VNC server
username?: string; // Username for authentication
password?: string; // Password for authentication
viewOnly?: boolean; // Enable view-only mode (default: false)
quality?: number; // Quality setting 0-9 (default: 6)
compression?: number; // Compression level 0-9 (default: 2)
autoResize?: boolean; // Auto-resize canvas (default: true)
scale?: number; // Scale factor 0.1-2.0 (default: 1.0)
timeout?: number; // Connection timeout ms (default: 10000)
debug?: boolean; // Enable debug logging (default: false)
}
`

#### Methods

- connect(): Promise - Connect to VNC server
- disconnect(): void - Disconnect from server
- sendKeyEvent(event: VNCKeyEvent): void - Send keyboard event
- sendPointerEvent(event: VNCPointerEvent): void - Send mouse event
- requestFramebufferUpdate(incremental?: boolean): void - Request screen update
- getState(): VNCConnectionState - Get current connection state
- on(event: string, handler: VNCEventHandler): void - Add event listener
- off(event: string, handler: VNCEventHandler): void - Remove event listener

$3

React hook for VNC client integration.

`typescript
const vncState = useVNC(options: UseVNCOptions);
`

#### Returns

`typescript
interface UseVNCReturn {
client: VNCClient | null;
state: VNCConnectionState;
connect: () => Promise;
disconnect: () => void;
sendKeyEvent: (event: VNCKeyEvent) => void;
sendPointerEvent: (event: VNCPointerEvent) => void;
requestUpdate: (incremental?: boolean) => void;
canvasRef: React.RefObject;
error: string | null;
loading: boolean;
}
`

$3

Ready-to-use React component with built-in UI.

`typescript
url="ws://localhost:6080"
autoConnect={true}
showStatus={true}
className="my-vnc-viewer"
style={{ width: '100%', height: '500px' }}
/>
`

#### Props

All VNCClientOptions plus:

- className?: string - Custom CSS class
- style?: React.CSSProperties - Custom styles
- showStatus?: boolean - Show connection status (default: true)
- showLoading?: boolean - Show loading indicator (default: true)
- disableKeyboard?: boolean - Disable keyboard input
- disableMouse?: boolean - Disable mouse input
- autoFocus?: boolean - Auto-focus canvas (default: true)
- connectButtonText?: string - Custom connect button text
- disconnectButtonText?: string - Custom disconnect button text

Events

The VNC client emits the following events:

- connecting - Connection attempt started
- connected - Successfully connected
- disconnected - Connection closed
- error - Connection or protocol error
- framebuffer-update - Screen update received
- server-cut-text - Clipboard data from server
- bell - Bell/beep from server
- resize - Server resolution changed

Advanced Usage

$3

`typescript
const client = new VNCClient({
url: 'ws://localhost:6080',
username: 'admin',
password: 'secretpassword'
});
`

$3

`typescript
const client = new VNCClient({
url: 'ws://localhost:6080',
quality: 9, // Highest quality
compression: 0 // No compression
});
`

$3

`typescript
url="ws://localhost:6080"
scale={0.5} // Scale down for mobile
autoResize={true} // Auto-resize to fit
disableKeyboard={true} // Disable for touch-only
/>
`

Server Setup

This library connects to VNC servers via WebSocket. You'll need a WebSocket-to-VNC proxy such as:

- websockify
- noVNC proxy
- Custom WebSocket proxy

Example with websockify:

`bash


Install websockify

`bash


Clone repository

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes.

Support

- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions

Acknowledgments

- Inspired by noVNC
- Built with modern TypeScript and React best practices