{"id":51102922,"url":"https://github.com/nasyx-rakeeb/realtime-mongo","last_synced_at":"2026-06-24T12:30:40.217Z","repository":{"id":365471522,"uuid":"1272218631","full_name":"nasyx-rakeeb/realtime-mongo","owner":"nasyx-rakeeb","description":"Firestore-like realtime document subscriptions for MongoDB via WebSockets and Change Streams.","archived":false,"fork":false,"pushed_at":"2026-06-17T13:32:10.000Z","size":174,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T14:22:31.946Z","etag":null,"topics":["change-streams","firestore-alternative","hooks","mongodb","pubsub","react","realtime","sync","typescript","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nasyx-rakeeb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T11:57:24.000Z","updated_at":"2026-06-17T13:34:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nasyx-rakeeb/realtime-mongo","commit_stats":null,"previous_names":["nasyx-rakeeb/realtime-mongo"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/nasyx-rakeeb/realtime-mongo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasyx-rakeeb%2Frealtime-mongo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasyx-rakeeb%2Frealtime-mongo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasyx-rakeeb%2Frealtime-mongo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasyx-rakeeb%2Frealtime-mongo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nasyx-rakeeb","download_url":"https://codeload.github.com/nasyx-rakeeb/realtime-mongo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasyx-rakeeb%2Frealtime-mongo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34733253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["change-streams","firestore-alternative","hooks","mongodb","pubsub","react","realtime","sync","typescript","websocket"],"created_at":"2026-06-24T12:30:38.350Z","updated_at":"2026-06-24T12:30:40.203Z","avatar_url":"https://github.com/nasyx-rakeeb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# realtime-mongo\n\nFirestore-like realtime document subscriptions for MongoDB. Subscribe to a document and receive live updates whenever it changes — powered by MongoDB Change Streams and WebSockets.\n\n```ts\n// Server — one call to start\nconst realtime = await createRealtimeMongo({\n  mongoUri: process.env.MONGO_URI!,\n  collections: ['mydb.tasks'],\n  port: 8080,\n});\n\n// Client — Firestore-like API\nconst unsubscribe = client\n  .collection\u003cTask\u003e('tasks')\n  .doc(taskId)\n  .onSnapshot((task) =\u003e {\n    console.log('Task updated:', task);\n  });\n```\n\n---\n\n## Packages\n\n| Package                                                | Description                                                                  | npm                                                                                                               |\n| ------------------------------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| [`@realtimemongo/server`](./packages/server/README.md) | Node.js server SDK — Change Streams, WebSocket server, auth                  | [![npm](https://img.shields.io/npm/v/@realtimemongo/server)](https://www.npmjs.com/package/@realtimemongo/server) |\n| [`@realtimemongo/client`](./packages/client/README.md) | Browser / Node.js client SDK — works with any JS framework                   | [![npm](https://img.shields.io/npm/v/@realtimemongo/client)](https://www.npmjs.com/package/@realtimemongo/client) |\n| [`@realtimemongo/react`](./packages/react/README.md)   | React hooks — `useDocument`, `useConnectionState`, `\u003cRealtimeMongoProvider\u003e` | [![npm](https://img.shields.io/npm/v/@realtimemongo/react)](https://www.npmjs.com/package/@realtimemongo/react)   |\n| `@realtimemongo/shared`                                | Internal protocol types (not installed directly)                             | —                                                                                                                 |\n\n---\n\n## Requirements\n\n- **MongoDB 6.0+** running as a **Replica Set** (required for Change Streams)\n- **Node.js 22.0.0+** on the server\n- **Any modern browser** on the client (Chrome 80+, Firefox 75+, Safari 14+, Edge 80+)\n\n---\n\n## Quick Start\n\n### 1. Install\n\n**Server:**\n\n```bash\nnpm install @realtimemongo/server\n```\n\n**Client (React):**\n\n```bash\nnpm install @realtimemongo/react @realtimemongo/client\n```\n\n**Client (Vue / Angular / plain JS):**\n\n```bash\nnpm install @realtimemongo/client\n```\n\n### 2. Start the server\n\n```ts\nimport { createRealtimeMongo } from '@realtimemongo/server';\n\nconst realtime = await createRealtimeMongo({\n  mongoUri: process.env.MONGO_URI!, // Must be a Replica Set URI\n  collections: ['mydb.tasks'], // Register each collection to watch\n  port: 8080,\n});\n\n// Graceful shutdown\nprocess.on('SIGTERM', () =\u003e realtime.stop());\n```\n\n### 3. Connect from React\n\n```tsx\nimport { RealtimeMongoProvider, useDocument } from '@realtimemongo/react';\n\nfunction App() {\n  return (\n    \u003cRealtimeMongoProvider url=\"ws://localhost:8080\" db=\"mydb\"\u003e\n      \u003cTaskView taskId=\"64a1b2c3d4e5f6a7b8c9d0e1\" /\u003e\n    \u003c/RealtimeMongoProvider\u003e\n  );\n}\n\ninterface Task {\n  title: string;\n  done: boolean;\n}\n\nfunction TaskView({ taskId }: { taskId: string }) {\n  const { data, loading, error } = useDocument\u003cTask\u003e('tasks', taskId);\n\n  if (loading) return \u003cp\u003eLoading…\u003c/p\u003e;\n  if (error) return \u003cp\u003eError: {error.message}\u003c/p\u003e;\n  if (!data) return \u003cp\u003eNot found\u003c/p\u003e;\n\n  return (\n    \u003ch1\u003e\n      {data.title} — {data.done ? 'Done' : 'In progress'}\n    \u003c/h1\u003e\n  );\n}\n```\n\n### 4. Connect from plain JavaScript\n\n```ts\nimport { RealtimeMongoClient } from '@realtimemongo/client';\n\nconst client = new RealtimeMongoClient({\n  url: 'ws://localhost:8080',\n  db: 'mydb',\n});\n\nconst unsubscribe = client\n  .collection\u003cTask\u003e('tasks')\n  .doc(taskId)\n  .onSnapshot(\n    (task) =\u003e console.log('Updated:', task),\n    (err) =\u003e console.error('Error:', err)\n  );\n\n// Stop listening\nunsubscribe();\n\n// Disconnect\nclient.close();\n```\n\n---\n\n## Authentication\n\nThe server supports a first-message token authentication pattern:\n\n```ts\n// Server\nconst realtime = await createRealtimeMongo({\n  mongoUri: process.env.MONGO_URI!,\n  collections: ['mydb.tasks'],\n  port: 8080,\n  transport: {\n    auth: {\n      verify: async (token) =\u003e {\n        const payload = verifyJWT(token, process.env.JWT_SECRET!);\n        return payload.userId;\n      },\n      canSubscribe: async (userId, db, coll, docId) =\u003e {\n        return await userOwnsDocument(userId, db, coll, docId);\n      },\n    },\n    allowedOrigins: ['https://app.example.com'],\n  },\n});\n\n// Client\nconst client = new RealtimeMongoClient({\n  url: 'wss://api.example.com',\n  db: 'mydb',\n  token: await getAuthToken(),\n});\n```\n\n---\n\n## Documentation\n\n| Document                               | Description                                   |\n| -------------------------------------- | --------------------------------------------- |\n| [Architecture](./docs/architecture.md) | System design, components, data flow          |\n| [Protocol](./docs/protocol.md)         | WebSocket message specification               |\n| [Security](./docs/security.md)         | Auth model, transport security, data exposure |\n| [Roadmap](./docs/roadmap.md)           | Planned features for v0.2, v0.3, and v1.0     |\n| [Contributing](./CONTRIBUTING.md)      | Development setup and PR process              |\n\n---\n\n## How It Works\n\n1. The server connects to MongoDB and opens a Change Stream on each registered database.\n2. When a client subscribes to `db.collection/docId`, the server fetches the current document and sends a `snap` message.\n3. When MongoDB emits a change event, the server looks up all subscribers for that document and fans out an `upd` or `del` message.\n4. The client applies causal ordering (VClock) to ensure stale or duplicate events are never delivered to callbacks.\n5. On reconnect, the client automatically re-subscribes to all active subscriptions.\n\nSee [docs/architecture.md](./docs/architecture.md) for the full system diagram and component breakdown.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasyx-rakeeb%2Frealtime-mongo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnasyx-rakeeb%2Frealtime-mongo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasyx-rakeeb%2Frealtime-mongo/lists"}