devlink-bridge

The WebSocket tunnel between your browser app and VSCode. Part 2 of 4 in the devlink system.

devlink-babel-plugin  ← stamps data-source at build time  
devlink-bridge        ← THIS PACKAGE: browser ↔ VSCode tunnel + cache
devlink-editor        ← Monaco editor panel
devlink-inspector     ← click-to-inspect overlay

How it works

The bridge has two parts:

• Browser SDK (devlink-bridge) — a small class you instantiate in your app. It opens a WebSocket to localhost, manages a file cache, and exposes readFile, writeFile, watchFile methods.
• VSCode Extension (extension/) — starts a local WebSocket server when VSCode opens. It handles file reads/writes using the real filesystem and pushes file changes to the browser whenever a watched file is saved on disk.

Files cross the bridge exactly once — after the first read they live in the browser-side cache. The extension's file watcher pushes changes automatically, so the cache stays fresh without polling.

Installation (Browser SDK)

npm install devlink-bridge
# or during development:
npm link devlink-bridge

Browser SDK usage

import { DevlinkBridge } from 'devlink-bridge';

const bridge = new DevlinkBridge({
  port: 7100,          // optional — auto-discovers if omitted
  heartbeatMs: 5000,   // ping interval
  timeoutMs: 10000,    // request timeout
  onStatusChange: (status) => console.log('Bridge:', status),
});

// Read a file (cached after first fetch)
const content = await bridge.readFile('/src/App.tsx');

// Write a file (debounce recommended — 500ms)
await bridge.writeFile('/src/App.tsx', newContent);

// Watch for changes pushed from VSCode
const unwatch = await bridge.watchFile('/src/App.tsx', (path, content) => {
  console.log('File changed on disk:', path);
});

// Read directory tree
const tree = await bridge.readDir('/src', true); // recursive

// Status
bridge.onStatusChange(status => {
  // 'connecting' | 'connected' | 'reconnecting' | 'disconnected'
});

// Debug
console.log(bridge.getCacheSnapshot());

// Cleanup
bridge.destroy();

VSCode Extension setup

The extension folder (extension/) is a standalone VSCode extension. Install it once on your machine.

Development (local install):

cd devlink-bridge/extension
npm install
npm run build

# Then in VSCode:
# Ctrl+Shift+P → "Extensions: Install from VSIX..."
# Or press F5 in VSCode to launch an Extension Development Host

What it does when active:

• Starts a WebSocket server on 127.0.0.1 (loopback only — not exposed to network)
• Scans ports 7100–7200, uses the first available one
• Shows the active port in the VSCode status bar: $(radio-tower) devlink :7100
• Watches files on request and pushes changes to all connected browsers
• Writes files directly to disk when the browser editor saves

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | port | number | auto | Try this port first before scanning | | portRange | [number, number] | [7100, 7200] | Range to scan for the extension | | heartbeatMs | number | 5000 | Ping interval in ms | | timeoutMs | number | 10000 | Request timeout in ms | | maxReconnectAttempts | number | Infinity | Stop trying after N failures | | reconnectBaseMs | number | 500 | Exponential backoff base | | onStatusChange | function | — | Called on every status change |

Connection status

bridge.onStatusChange(status => {
  switch (status) {
    case 'connecting':    // first connect attempt
    case 'connected':     // handshake complete, ready
    case 'reconnecting':  // lost connection, retrying with backoff
    case 'disconnected':  // gave up or destroyed
  }
});

Security

The WebSocket server binds to 127.0.0.1 only — it is never accessible from other machines on your network. It is a dev-only tool and should never run in production.

License

MIT