Repository navigation
Improvements
- 🪪 Persistent user identities & multi-tab presence (
userId) - every participant gets an unforgeableuserIdalongside each tab'speerId(await room.getSelf()), persisted across browser reloads and open tabs by default (identity: 'local'). Passidentity: 'none'for throwaway IDs, reset saved browser identity withclearUserIdentity(appId), or bring portable keys across devices and servers withcreateUserIdentity(),exportUserIdentity(), andimportUserIdentity(). Track unique users instead of individual tabs withroom.onUserJoin(),room.onUserLeave(), androom.getUsers(), and pass either auserIdorpeerIdtotarget/targetsacross actions, media,ping(), and moderation. - 🗂️ Synced per-user & shared room state (
makeUserState&makeState) - built-in JSON state primitives that apply local updates synchronously, support customvalidate(next, context)rules, and plug directly into React'suseSyncExternalStore: -room.makeUserState(name, initialValue?, config?)gives each user their own presence-scoped slot (.get(),.getAll(),.has(),.set(),.clear(),.onChange()), ready to read insideonUserJoinand cleaned up automatically when they leave. -room.makeState(name, initialValue?, config?)syncs shared state across the room (.get(),.set(),.onChange()), including to late joiners even after the original writer has left. - 👑 Room admins, custom roles & moderation (
roles()) - passuse: [roles(...)]tojoinRoom()for serverless permissions and moderation. Create host-owned rooms withroles({selfAsAdmin: true})(which embeds the host'suserIdinroomIdfor shareable invite links and restores admin rights on rejoin) or pin trusted IDs withroles({admins: [...]}). Admins can manage custom roles (grantRole,revokeRole,getRoles,onRoleChange) and ban/unban users (ban,unban,isBanned), whilemakeState,makeUserState, andmakeActionaccept{roles}to restrict who can write or send (makeStatedefaults to admin-only writes whenroles()is enabled; passroles: '*'to allow everyone). - 🕸️ Large-room scaling (
scale()) - passuse: [scale({maxDirectPeers?})]tojoinRoom()to scale rooms to dozens of peers without changing your state, action, or media code (withroom.getTopology()to inspect active connections and routes). - 🚪 Room size limits (
maxUsers) - cap how many unique users can join a room (joinRoom({appId, maxUsers: 2}, roomId)); extra joiners are rejected with{code: 'room-full'}onroom.onError(). - 🔔 Composable event subscriptions - room, action, and state
on*()methods now support multiple independent listeners, return anunsubscribe()function, and accept{once, signal}options plus{replay: true}to emit already-active users, peers, streams, roles, or state to late subscribers. - 🚨 Structured error handling (
room.onError&ActionError) -room.onError()emits typedRoomErrorcodes ('room-full','banned','decrypt-failed','peer-connect-failed','relay-failed', etc.), and rejectedaction.send()/action.request()calls expose a typedActionError(err.kind:'timeout' | 'disconnected' | 'aborted' | 'rejected').
⚠️ Breaking changes
0.27.0 uses a new wire protocol and is not compatible with 0.26.x peers — upgrade all clients sharing a room together. See the 0.27.0 migration guide for full before/after examples.
- Event listeners are now
on*(fn, options?)methods - replace property assignments (room.onPeerJoin = fn,action.onMessage = fn) andmakeActionconfig callbacks withon*()calls (room.onUserJoin,room.onPeerJoin,room.onPeerStream,action.onMessage,action.onRequest,action.onReceive,action.onReceiveProgress), which return anunsubscribe()function: - Room and media callbacks now receive{userId, peerId, ...}context objects instead of a barepeerIdstring (onPeerStreampasses(stream, {userId, peerId, metadata})). - Join, stream, role, and state listeners only fire for new events by default; pass{replay: true}to synchronously emit existing items on subscribe. -action.onRequestandaction.onReceiveallow one active handler per action at a time (callunsubscribe()before replacing).
const room = joinRoom({appId: 'example.com/my-app'}, 'lobby')
const {userId, peerId} = await room.getSelf()
const offJoin = room.onUserJoin(({userId}) => console.log(`${userId} joined`))
room.onPeerStream((stream, {userId, metadata}) =>
attachVideo(userId, stream, metadata)
)
room.onError(err => console.error(err.code, err.message))
const chat = room.makeAction('chat')
chat.onMessage((text, {userId}) => renderMessage(userId, text)) selfIdreplaced byawait room.getSelf()- the top-levelselfIdexport has been removed; read{userId, peerId}fromawait room.getSelf()after joining a room (or awaitroom.ready).joinRoom(config, roomId)takes 2 arguments and throws on duplicate active joins - moveonJoinErrortoroom.onError(err => ...).onPeerHandshakeandhandshakeTimeoutMshave been removed in favor of verifieduserIds,makeUserState,maxUsers,roles(), andaction.onReceive. CallingjoinRoom()while(appId, roomId)is already active now throws instead of returning the existing room (callawait room.leave()before rejoining), androom.isPassive()has been removed.- Targeted
action.send()rejects on disconnected targets - passing{target}toaction.send(data, {target})now rejects if a targeteduserIdorpeerIdis not connected (broadcastsend(data)withouttargetstill resolves when the room is empty). - Streamlined
MediaStreamAPI -addStream()andreplaceTrack()now returnPromise<void>instead ofPromise<void>[].addTrack,removeTrack,onPeerTrack, andmetadataonreplaceTrackhave been removed — mutate tracks on yourMediaStreamand re-call idempotentawait room.addStream(stream, {metadata})to sync track or metadata updates. room.getPeers()returnsPeerInfoobjects -getPeers()now returns{[peerId]: {userId, connection, direct, hops, roles}}instead of rawRTCPeerConnectioninstances (peers[peerId].connectionaccesses the underlying connection on direct peers; preferroom.getUsers()for participant lists).- Relay connectivity & package exports -
relayConfig.manualReconnection,pauseRelayReconnection(), andresumeRelayReconnection()have been replaced bysetRelayConnectivity('offline' | 'online' | 'auto'). Deprecatedtrystero/<strategy>subpaths, prebuilt.min.jsbundles, and@trystero-p2p/ipfshave been removed — importtrystero(Nostr) or@trystero-p2p/<strategy>directly. TypeScript projects now require TypeScript >= 5.0, andwsis an optional peer dependency needed only for@trystero-p2p/ws-relay/server.