Folkways Developers

Everything to build with Folkways

Docs, the JavaScript SDK, guides, reference and examples. Publish and subscribe to live events with stream, kv and signal; reconnects, replay and token refresh are handled for you.

Quick start Browse the docs

@folkwaysio/realtime is published on npm for browsers, React Native, Node.js, Deno and Bun.

Install
npm install @folkwaysio/realtime
Connect, subscribe, publish
import { Folkways } from '@folkwaysio/realtime';

const client = await Folkways.connect({
  authUrl: '/api/realtime-token',
});

const chat = client.topic('chat/lobby');
chat.subscribe((msg) => show(msg.data), { from: { last: 20 } });
await chat.publish('message', { text: 'Hello!' });

Start here

Four pages take you from an empty dashboard to a working connection.

  1. 01Set up the dashboardCreate a segment, topic rules and a signing key.
  2. 02InstallationInstall @folkwaysio/realtime for your runtime.
  3. 03Quick startA token endpoint, a connection, your first publish.
  4. 04Key conceptsSegments, topics, identities and tokens.

Guides

Reference

Client APIFolkways.Realtime and connect().Client optionsEvery option, its default and meaning.Topics APIpublish, subscribe, values and messages.Server APIFolkways.Rest: tokens and publishing.Error codesEvery code, whether to retry, what it means.Current limitationsWhat works today and what is coming.

Examples

React example appThe full example behind the “Using it with React” guide.AI streamingToken streams that survive reloads and reconnects.Live dashboardsCurrent values for every screen, with publishable keys.MultiplayerStrokes, selections and cursors on one board.
SDK source on GitHub

Common questions

What is Folkways?
Folkways is hosted real-time infrastructure. Your apps publish and subscribe to live events on topics, and the JavaScript SDK handles reconnects, replay and token refresh for you. Key concepts
Which platforms does the JavaScript SDK support?
Browsers, React Native, Node.js, Deno and Bun. Install it with npm install @folkwaysio/realtime. It includes TypeScript declarations. Installation
How do users authenticate?
Your backend signs a short-lived token for each user with @folkwaysio/realtime/server; tokens live at most 15 minutes. The SDK asks your endpoint for a new token about a minute before the current one expires, without dropping subscriptions. Public pages can use a read-only publishable key instead. How authentication works
What happens when the connection drops?
The SDK reconnects on its own and queues publishes in the meantime. After reconnecting it resubscribes every topic from the last event you handled, then sends the queued publishes. Connection and reconnects
When should I use stream, kv or signal?
Use stream for ordered events you can replay, such as chat messages or AI tokens. Use kv for state: only the latest value per key is kept, and new subscribers get the current values first. Use signal for short-lived activity such as typing and cursors: signals are not stored, and each sender’s latest one is kept for 5 seconds. Topics and events

SDKs

  • JavaScript / TypeScript
  • Python · not yet available
  • Go · not yet available
  • Java / Kotlin · not yet available
  • Swift · not yet available