Installation
Install @folkways/realtime from source until the first npm release, then from npm.
Until the first release: build from source
@folkways/realtime is not on npm yet. Build it from the public repository and install the package file:
git clone https://github.com/Folkways/folkways-js
cd folkways-js
pnpm install
pnpm --filter @folkways/realtime build
cd packages/realtime && pnpm pack # writes folkways-realtime-0.1.0.tgzThen, in your app:
npm install /path/to/folkways-js/packages/realtime/folkways-realtime-0.1.0.tgzYou need Node.js 20 or newer and pnpm to build it.
After the first release
npm install @folkways/realtimeWhat is in the package
| Import | Use it in |
|---|---|
@folkways/realtime | Your app: browsers, React Native, Node.js, Deno, Bun |
@folkways/realtime/server | Your backend only: signs tokens and publishes over HTTP |
@folkways/realtime/stores/indexeddb | Browsers: keep cursors, unsent messages and a cache across reloads |
@folkways/realtime/stores/async-storage | React Native: the same, in AsyncStorage |
@folkways/realtime/stores/file | Node.js: the same, in a directory |
@folkways/realtime/iife | A script-tag bundle that defines a global Folkways |
The package has one dependency, flatbuffers, and is marked side-effect free, so bundlers drop what you don't use.
Runtimes
| Runtime | Notes |
|---|---|
| Browsers | Any modern browser. Needs BigInt (all current browsers have it). |
| Node.js 22+ | Works as is. |
| Node.js 20 | Has no global WebSocket. Pass one from the ws package, see below. |
| React Native | Needs a crypto.getRandomValues polyfill, such as react-native-get-random-values. |
| Deno, Bun | Work as is. |
import { WebSocket } from 'ws';
import { Folkways } from '@folkways/realtime';
const client = new Folkways.Realtime({ url: 'https://rte.example.com', token, webSocket: WebSocket });Script tag
The package includes a browser bundle that defines a global Folkways. Serve
node_modules/@folkways/realtime/dist/index.global.js from your site (or a CDN after the npm release):
<script src="/vendor/folkways/index.global.js"></script>
<script>
const client = new Folkways.Realtime({ url: 'https://rte.example.com', authUrl: '/api/realtime-token' });
client.connect().then((session) => console.log('connected as', session.identity));
</script>