README.md

January 7, 2023 · View on GitHub

pluv.io

TypeSafe Primitives for a Realtime Web

💕 Inspired by trpc 💕 yjs 💕
and Cloudflare Workers 💕

Intro

pluv.io allows you to more easily build realtime multiplayer experiences with a fully typesafe API and powerful abstractions as primitives, so that you can focus on building for your end users.

Self-host on Cloudflare Workers or Node.js; or get started on the pluv.io network.

Preview

Create your pluv.io backend

// backend
const io = createIO(
  platformNode({
    context: () => ({ db }),
    crdt: yjs,
  })
);

export const ioServer = io.server({
  getInitialStorage: async ({ context: { db }, room }) => {
    return await db.room
      .findUnique({ where: { id: room } })
      .then((result) => result?.encodedState ?? null);
  },
  router: io.router({
    sendGreeting: io.procedure
      .input(z.object({ message: z.string() }))
      .broadcast(({ message }) => ({
        receiveGreeting: { message }
      }))
  })
});

Create your frontend client with your backend types

// frontend
const types = infer((i) => ({ io: i<typeof ioServer> }));
const io = createClient({
  types,
  initialStorage: yjs.doc((t) => ({
    messages: t.array<string>("messages"),
  })),
  presence: z.object({
    selectionId: z.string().nullable()
  })
});

const {
  event,
  useBroadcast,
  useMyPresence,
  useOthers,
  useStorage
} = createBundle(io);

Use powerful primitives to build realtime features

// react
event.receiveGreeting.useEvent(({ data }) => { /* ... */});
//                                ^? const data: { message: string }

const broadcast = useBroadcast();

broadcast.sendGreeting({ message: "hello world" });
//        ^? const sendGreeting: (data: { message: string }) => void

const [mySelection, update] = useMyPresence((presence) => {
//     ^? const mySelection: string | null
  return presence.selectionId;
});

const others = useOthers((others) => {
//    ^? const others = string[]
  return others.map((other) => other.presence.selectionId);
});

const [
  messages,
// ^? const messages: string[] | null
  sharedType
// ^? YArray<string> | null
] = useStorage("messages");

Documentation

The full documentation is available at pluv.io.

Features

✅ Automatic type-safety
✅ Basic events
✅ Rooms
✅ Authentication
✅ Awareness + Presence
✅ CRDTs
- ✅ Yjs
  - ✅ Provider
  - ✅ Shared Types
    - ✅ Map
    - ✅ Array
    - ✅ Text
    - ✅ XmlFragment
    - ✅ XmlElement
    - ✅ XmlText
- ✅ Loro (preview)
  - ✅ Containers
    - ✅ Counter
    - ✅ List
    - ✅ Map
    - ✅ Moveable List
    - ✅ Text
    - ✅ Tree
⬜ Studio (admin & developer panel)

Runtimes

✅ Cloudflare Workers
- WebSocket API
  - ✅ Hibernation API (default, recommended)
  - ✅ Standard API
- State Persistence
  - ✅ SQLite-backed Durable Objects (default, recommended)
  - ✅ Key-value storage-backed Durable Object
✅ Node.js
- ✅ PubSubs
  - ✅ Redis (preview)
  - ⬜ MQTT
- ✅ State Persistence
  - ✅ In-memory (default)
  - ✅ Redis (preview)

Frontends Frameworks

✅ React.js
⬜ Solid.js
⬜ Vue.js
⬜ Svelte

Packages

@pluv/io - Server
@pluv/client - Framework agnostic client
@pluv/react - Integrate @pluv/client with React.js
@pluv/platform-pluv - Adapter to run on pluv.io
@pluv/platform-cloudflare - Adapter to run on Cloudflare Workers
@pluv/platform-node - Adapter to run on Node.js
@pluv/crdt-yjs - Yjs CRDT adapter
@pluv/crdt-loro - Loro CRDT adapter
@pluv/persistence-redis - Persistence for storage on distributed systems (Node.js only)
@pluv/persistence-cloudflare-transactional-storage - Durable Object persistent state for WebSocket hibernation
@pluv/pubsub-redis - PubSub for rooms across distributed systems

Credits

This software uses the following open source tooling and libraries:

License

MIT

pluv.io

TypeSafe Primitives for a Realtime Web

💕 Inspired by trpc 💕 yjs 💕 and Cloudflare Workers 💕

💕 Inspired by trpc 💕 yjs 💕
and Cloudflare Workers 💕