Skip to content

README.md

Latest commit

 

History

History
102 lines (78 loc) · 5.84 KB

README.md

File metadata and controls

102 lines (78 loc) · 5.84 KB

Collab Code

Google Docs–style real-time collaboration on a single code file in VS Code or Cursor. See who's in the room and where their cursor is (presence + gutter).

Quick start

  1. Open this folder in Cursor or VS Code (File → Open Folder → select this project).
  2. Add your Liveblocks key (one-time setup):
    • Copy .vscode/settings.json.example → .vscode/settings.json
    • Get your public key from Liveblocks (create a project, copy the Public key)
    • In .vscode/settings.json, replace pk_your_liveblocks_public_key with your real key
    • Commit settings.json so collaborators use the same key (public keys are safe to commit)
  3. Build & run: Terminal → Run Task → npm: compile (or npm run compile), then press F5.
  4. In the new window that opens: open a file → Command Palette (Cmd+Shift+P) → Collab Code: Start collaboration → share the room ID with others.

Setup (one key for the whole project)

Only one person needs a Liveblocks account. Everyone else just clones the repo—they don’t need to add any key.

Step What to do
1 Get your public key from Liveblocks (create a project → copy Public key).
2 In this repo: copy .vscode/settings.json.example to .vscode/settings.json.
3 In .vscode/settings.json, replace pk_your_liveblocks_public_key with your real key.
4 Commit .vscode/settings.json. Anyone who clones the repo will use that key automatically.

Optional (per user, in their own settings): collabCode.displayName, collabCode.cursorColor.

Project structure

CoLabCode/
├── src/                    # Extension source (TypeScript)
│   ├── extension.ts        # Entry point: activates commands, wires editor events to presence
│   ├── commands.ts         # Start / Join / Leave / Copy link; room ID handling and API key checks
│   ├── state.ts            # In-memory state: current room ID and collaborative file URI
│   ├── liveblocks.ts       # Liveblocks client, room join/leave, Yjs provider and shared Y.Doc
│   ├── binding.ts          # Two-way sync: VS Code TextDocument ↔ Y.Text (doc ↔ Liveblocks)
│   └── presence.ts         # Presence UI: status bar (“who’s here”), gutter cursors, selection highlights
├── out/                    # Compiled JS (from npm run compile); do not edit
├── .vscode/
│   ├── settings.json.example   # Template for Liveblocks public key
│   ├── settings.json           # Your key (create from example; safe to commit)
│   ├── launch.json             # F5 runs Extension Development Host
│   └── tasks.json              # npm: compile task
├── package.json            # Extension manifest, scripts, dependencies (Liveblocks, Yjs)
├── build.mjs               # Build script (esbuild) — compiles src/*.ts → out/*.js
└── collab-code-0.1.0.vsix  # Packaged extension (after npm run package)
Layer Role
extension.ts Registers commands and hooks editor selection/active-editor changes to presence. On deactivate: leaves room, unbinds document, detaches presence.
commands.ts Implements the four commands; reads workspace config (API key, display name, cursor color); creates/joins Liveblocks room and binds the open file.
state.ts Holds currentRoomId and currentFileUri so the rest of the extension knows which room and file are active.
liveblocks.ts Liveblocks client + room lifecycle; provides the Yjs document that syncs with the room. Defines CollabPresence (cursor, selection, name, color).
binding.ts Binds a TextDocument to a Y.Text: local edits go to Yjs (then Liveblocks); remote updates from Yjs are applied to the document (with local-origin filtering to avoid echo).
presence.ts Subscribes to others’ presence; updates status bar; draws gutter decorations and selection ranges for other users’ cursors.

Running the extension

Option A – Development (F5)

  1. Open this project folder in Cursor or VS Code.
  2. Ensure .vscode/settings.json exists with your real pk_... key (see Setup).
  3. Terminal → Run Task → npm: compile (or npm run compile).
  4. Press F5. A new window opens with the extension loaded.
  5. In that new window: open a file → Collab Code: Start collaboration (or Join with code).

Option B – Install from VSIX (when F5 / Extension Host doesn’t work)

  1. In this project: npm run compile then npx @vscode/vsce package.
  2. In Cursor: Cmd+Shift+P → Extensions: Install from VSIX → select the .vsix from this project.
  3. Reload the window. Open any folder that has .vscode/settings.json with your Liveblocks key and use Collab Code: Start collaboration there.

Commands

Command What it does
Collab Code: Start collaboration Start a session; copies room ID to clipboard. Share that ID so others can join.
Collab Code: Join with code Paste a room ID to join an existing session.
Collab Code: Leave collaboration Leave the current session.
Collab Code: Copy share link Copy a shareable link for the current room.

Troubleshooting

Issue Fix
F5 does nothing / new window never opens Use Option B and install from the .vsix file.
"Set your Liveblocks public API key" Create .vscode/settings.json from .vscode/settings.json.example and put your real pk_... key in it.
Commands not found Run the commands in the new window (Extension Development Host), not the window where you pressed F5.