LiWebJS

Lightweight realtime backend framework for Node.js

Channels, rooms, shared state, auth, heartbeat, and presence — all built in.

Documentation · npm · Examples

---

Why LiWebJS?

Every realtime project ends up re-implementing the same patterns from scratch.

Raw WebSocket	LiWebJS
ws.on("message", fn)	liweb.handle("chat:message", fn)
Manual room tracking	channel("chat").room("general")
Custom auth handling	options.auth = { secret: "..." }
Manual state sync	room.state.set / get / push / patch
Manual heartbeat	options.ping = { pingInterval: 25000 }
Manual presence tracking	room.presence.online() / lastSeen()

LiWebJS promotes these to first-class framework features so you write application logic — not infrastructure.

---

Packages

Package	Description	npm
liwebjs	Server-side Node.js framework
liwebjs-client	Browser WebSocket client SDK

---

Quick Start

npm install liwebjs
npm install liwebjs-client

Server:

import http from "http";
import { createLiWebServer } from "liwebjs";

const httpServer = http.createServer();
const liweb = createLiWebServer(httpServer);

const general = liweb.channel("chat").room("general");

liweb.on("connection", (ctx) => {
  general.join(ctx.connection, ctx.user);
  ctx.send("welcome", { id: ctx.connection.id });
});

liweb.handle("message", (ctx) => {
  general.emit("message", ctx.payload);
});

liweb.on("disconnect", (ctx) => {
  general.leave(ctx.connection);
});

httpServer.listen(3001);

Client:

import { createLiWebClient } from "liwebjs-client";

const client = createLiWebClient("ws://localhost:3001");

client.on("connect", () => console.log("connected"));
client.handle("message", (payload) => console.log(payload));
client.emit("message", { text: "hello world" });

---

Features

Feature	Status
Event routing	✅
Channels + Rooms	✅
Shared state engine	✅
Secret-based auth	✅
Ping/Pong heartbeat	✅
Presence engine	✅
Browser client SDK + auto-reconnect	✅
TypeScript-first	✅

---

Documentation

Full API reference, guides, and examples:

👉 liwebjs.sumeet.app

---

Example App

Full-stack chat app — Express + React + Vite:

# Terminal 1
cd examples/chat/server && npm install && npm run dev

# Terminal 2
cd examples/chat/client && npm install && npm run dev

Open http://localhost:5173 in multiple tabs.

---

Roadmap

v0.0.1  ✅  Core framework — events, rooms, state, auth, heartbeat
v0.0.2  ✅  npm publish + documentation
v0.0.3  ✅  Presence Engine — online tracking, last seen, activity
v0.0.4  🔜  Role-based authorization
v1.0.0  🔜  Redis distributed state adapter
Future  🔜  uWebSockets adapter, Edge runtime support

---

Development

git clone https://github.com/sumeet57/liwebjs.git
cd liwebjs && npm install

cd packages/core && npm test
cd ../client && npm test

See CONTRIBUTING.md for guidelines.

---

When NOT to Use LiWebJS

• You need ultra-low latency at massive scale — consider raw ws or uWebSockets
• You already rely heavily on the Socket.IO ecosystem
• You need multi-server scaling right now — Redis adapter is planned for v1.0

---

License

MIT © Sumeet Umbalkar