---
title: swarm-kit
description: swarm-kit is a TypeScript library of higher-level data structures over Freedom's window.swarm provider: records, feeds, hash chains, multi-writer feeds, encryption and live messaging.
kick: Swarm
dek: A library of reusable data structures on top of window.swarm, from JSON chunks to multi-writer feeds and live chat rooms. Early prototype, not on npm yet.
source: https://github.com/solardev-xyz/swarm-kit
---
[swarm-kit](https://github.com/solardev-xyz/swarm-kit) turns the provider's
low-level chunk and single-owner-chunk calls into structures apps need. It
only talks to `window.swarm`, so Freedom stays in charge of permissions,
signing, postage and limits. It is not a Bee client and does not run against
a plain node.
Early prototype The package is marked
private in its package.json and is not published to
npm. Expect API changes.
## Get it
```sh
git clone https://github.com/solardev-xyz/swarm-kit.git
cd swarm-kit
npm install
npm run typecheck && npm test
npm run build
```
`npm run build` compiles the library to `dist/` and also writes a
self-contained browser bundle, `swarm-kit.js`, into each folder under
`examples/`. The examples import it directly:
```javascript
import { createSwarmKit, waitForSwarm } from './swarm-kit.js';
```
The simplest way to use swarm-kit in your own page is the same: copy one of
those bundles next to your HTML. If you use a bundler, the package's
`prepare` script builds `dist/` on install, so a git dependency should work,
but the project does not document that route.
## Basic use
```javascript
import { createSwarmKit, waitForSwarm } from './swarm-kit.js';
const provider = await waitForSwarm({ requireFreedomBrowser: true });
const kit = createSwarmKit(provider);
await kit.requestAccess();
const chunk = await kit.chunks.publishJson({ hello: 'swarm' });
console.log(await kit.chunks.readJson(chunk.reference));
```
`createSwarmKit(window.swarm)` is equivalent; the provider is wrapped in a
byte-oriented driver either way.
## What is in it
| Need | Use |
| ---- | --- |
| Small immutable values | `kit.chunks` (one content-addressed chunk) |
| Larger immutable values | `kit.objects` (split across chunks) |
| Values at a key you choose | `kit.soc`, with `deriveIdentifier` for namespaced identifiers |
| An append-only stream | `createIndexedSocStream`, `kit.hashChain` |
| A revisioned record or lookup table | `kit.records`, `kit.lookup` |
| Reads by time | `kit.epochFeed` |
| Many writers, one view | `kit.multiWriterFeed` |
| Revisioned documents | `kit.did` |
| Encryption and signatures | `kit.crypto` (AES-GCM, P-256 ECDH), `kit.signedDocuments` (P-256 and Ethereum wallets) |
| Sealed values | `kit.commitReveal` |
| Real time | `kit.live.topic`, `kit.live.bus`, `kit.live.inbox`, `kit.live.multiWriterFeed` |
| Checking a provider | `runSwarmProviderCompliance` |
The full map, with examples for each, is in the
[README](https://github.com/solardev-xyz/swarm-kit#primitive-map).
Two rules the library builds on:
- **Single-owner chunk identifiers are write-once.** Writing the same owner and
identifier twice is undefined at the network layer, so append-only
structures use a fresh, deterministic identifier per entry.
- **Live messaging is a hint.** The `kit.live.*` primitives need
`features.includes('messaging')`. Delivery is best-effort, unordered,
at-least-once and unauthenticated; durable Swarm structures are the source
of truth. Prefer one `kit.live.bus` per app over a topic per widget, since
subscriptions are bounded node-wide. See [Live messaging](guide-messaging.html.md).
## Run the examples locally
Each example has a dev server that serves it on `127.0.0.1`. Open the URL in
Freedom Browser, which injects the real `window.swarm`:
| Command | Example | Default port | Port variable |
| ------- | ------- | ------------ | ------------- |
| `npm run dev:playground` | Playground (epoch feeds and more) | 4173 | `SWARM_KIT_SMOKE_PORT` |
| `npm run dev:provider-compliance` | Provider compliance checks | 4175 | `SWARM_KIT_PROVIDER_COMPLIANCE_PORT` |
| `npm run dev:test-center` | Swarm Provider Test Center | 4176 | `SWARM_KIT_TEST_CENTER_PORT` |
| `npm run dev:chat` | Live chat | 4177 | `SWARM_KIT_CHAT_PORT` |
`PORT` and `HOST` override any of them, for example
`PORT=4174 npm run dev:playground`. To deploy an example instead, run
`npm run build`, upload its folder to Swarm and open the `bzz://` URL.
The compliance page writes small test chunks and checks the provider
behaviours swarm-kit relies on. Run it when you suspect a provider bug.
### Chat across two identities
The chat example suggests opening the same room in a second Freedom profile,
with its own node and identity. Today every profile's Swarm node uses the
same local API port, so two profiles cannot run at the same time
([#993](https://github.com/solardev-xyz/freedom-browser/issues/993)). Until
that is fixed, use a second machine.