Jazz TS refers to the TypeScript preset and runtime support that the Jazz ecosystem ships to help developers build peer-to-peer synchronized apps. This preset configures TypeScript strictness and module resolution to align with Jazz’s secure by-default model, gives first-class types for encrypted records, and supports automatic schema migrations. The preset targets durable peer-to-peer collaboration rather than centralized server persistence, and it is suitable for long-lived desktop and web clients that must remain interoperable across sessions and devices.
What Jazz TS is and why it exists
Jazz TS is a curated TypeScript preset intended to reduce friction when building with the Jazz protocol. It provides strict, capability-safe types for encrypted documents, secure invitations, presence, and histories. Rather than assuming a centralized backend, Jazz assumes multiple peers, offline edits, and eventual merge. The preset aligns compiler settings with these assumptions, improving type safety for replication, undo/redo, invite links, and device-to-device synchronization while remaining practical for production web and Electron apps.
Core features and capabilities
The Jazz preset exposes runtime modules that manage document encryption, peer discovery, and sync. It emphasizes capability-based security so that only invited peers can access specific collections. Typical features include:
- Encrypted mutable documents with merge-safe CRDT semantics
- Presence and history APIs scoped to invitations
- Schema migration tooling that preserves privacy and type safety
- Type-safe selectors and reactive bindings for UI frameworks
Type safety for encrypted models
Jazz models are stored as encrypted JSON-like structures. The preset provides strong typing for these structures while keeping encryption transparent to most business logic. Developers define models as TypeScript interfaces or Zod schemas; the preset generates types that enforce access patterns and validate shape during local operations, with cryptographic protections applied at persistence and transmission boundaries.
Invitations and multi-peer collaboration
Jazz handles invitations as first-class objects that carry both authorization and transport hints. Types model invite states, link records, and permissions, so invitation acceptance, revocation, and expiration are represented safely in code. This makes role-based access and device-bound permissions explicit in the type system, reducing runtime surprises when peers come and go.
Common use cases and practical scenarios
Jazz TS shines in scenarios where users need to collaborate offline and reconcile later, or where privacy is a first-class requirement. Typical use cases include secure team editors, private whiteboards, note apps with selective sharing, and apps that must interoperate across desktop, mobile, and web. It is less suitable for apps that require strict centralized audit trails or server-side business logic enforcement, since Jazz prioritizes peer authority and eventual consistency.
How Jazz TS compares to alternatives
Compared to general-purpose CRDT libraries, Jazz bundles protocol, encryption, and schema tooling into one preset. Compared to Firebase or traditional backend-centric backends, Jazz removes a centralized choke point and shifts authorization to the invite layer. The table below summarizes key dimensions of this tradeoff.
Comparative overview
| Dimension | Jazz TS preset | Typical CRDT-only library | Centralized backend (e.g., Firebase) |
|---|---|---|---|
| Architecture | Peer-to-peer with encrypted sync | Peer-to-peer or client-server | Client-server |
| Encryption model | End-to-end by default | Usually offload to developer | Server-managed at rest and in transit |
| Schema & migrations | Built-in, privacy-aware tooling | Library-specific or custom | DB schema migrations, server logic |
| Presence & history | Integrated invitations and scoped history | Often custom | Often server-centric |
| Trust model | Clients are authoritative; server relay only | Varies | Server authoritative |
Getting started with Jazz TS
To use Jazz TS, install the preset and runtime packages, then configure TypeScript to target the Jazz preset’s recommended compiler settings. Typical steps include enabling strict mode, setting module resolution to preserve secure defaults, and importing Jazz’s types for models, invites, and presence. From there you can create encrypted documents, invite peers, and build reactive UI bindings with type-safe selectors.
Migration and versioning considerations
Jazz includes schema migration helpers that let you evolve document types without breaking existing encrypted data. When you change a model, you can declare a migration that rewrites encrypted blobs for affected peers. The preset encodes version metadata so clients can detect when a document requires migration and apply the correct transforms, keeping interoperability across different client versions.
Limitations and responsible usage
Jazz TS is not a universal replacement for server-side logic; it assumes developers handle application rules within peer-authorized flows. Performance at very large scale depends on document shape and peer count, and encryption adds overhead relative to plaintext CRDTs. The preset evolves with the protocol, so early adopters should pin versions and monitor changelogs for breaking changes during upgrades.
Status and forward direction
The Jazz TS preset is maintained as an evergreen component of the Jazz ecosystem, with periodic releases aligned to protocol improvements. It follows semantic versioning for the preset package and treats breaking changes as infrequent, well-communicated events. Projects choosing Jazz TS should plan for gradual adoption, schema versioning, and testing across peer environments to ensure smooth collaboration and migration behavior over time.