Skip to content

AGENTS.md

Latest commit

 

History

History
39 lines (25 loc) · 1.98 KB

AGENTS.md

File metadata and controls

39 lines (25 loc) · 1.98 KB

AGENTS.md

Guidance for coding agents working in this repository.

Project

@y/websocket — WebSocket provider for Yjs. Client library that connects a Y.Doc to a y-websocket-compatible backend and syncs document updates + awareness. Also supports cross-tab communication via BroadcastChannel / localStorage.

The server implementation lives in a separate repo: @y/websocket-server.

Layout

  • src/y-websocket.js — the entire provider implementation (single file, ESM).
  • test/index.js — test runner entry point.
  • test/y-websocket.test.js — integration tests; spin up @y/websocket-server in-process and exercise a real client.
  • dist/ — generated by npm run dist (rollup CJS bundle + tsc declarations from JSDoc). Do not edit by hand.
  • rollup.config.mjs, tsconfig.json — build config.

Commands

  • npm test — runs node ./test/index.js. Tests require a real backend (started inside the test file).
  • npm run lint — runs standard + tsc --skipLibCheck. Must pass before shipping.
  • npm run dist — clean + rollup + emit .d.ts from JSDoc.

Conventions

  • JavaScript + JSDoc, not TypeScript. Types are emitted from JSDoc annotations via tsc; keep annotations accurate.
  • standard style (no semicolons, 2-space indent, single quotes). npm run lint enforces it.
  • ESM only ("type": "module"). The CJS build exists only in dist/.
  • Dependencies are kept minimal: lib0 (utilities) and @y/protocols (sync + awareness wire protocol). Prefer reusing what's in lib0 over adding new deps.
  • Peer dep on @y/y (Yjs).

Testing

Use the lib0/testing framework (see the lib0-testing skill for patterns). Tests run against a live @y/websocket-server started via import '@y/websocket-server/server' — don't mock the socket layer.

Release

preversion runs npm run dist and asserts the CJS bundle and .d.ts exist before npm version proceeds. Current version is a 4.0.0-rc line.