Skip to content
plasma

Install

plasma ships as five installable packages. Most apps pull in all of them; you can drop the ones you don’t need (e.g. omit @sh1n4ps/plasma-react if you consume the store from Solid or vanilla JS).

Requirements

Section titled “Requirements”
  • Node.js 20+ — the build tooling
  • TypeScript 5.7+ — plasma’s phantom types need modern inference
  • A Cloudflare Workers project (for the server side; local dev works against Miniflare)

Add the packages

Section titled “Add the packages”
Terminal window
pnpm add @sh1n4ps/plasma-core @sh1n4ps/plasma-client @sh1n4ps/plasma-server @sh1n4ps/plasma-react

Optional packages

Section titled “Optional packages”
Package When to add it
@sh1n4ps/plasma-devtools You want the in-page inspector and/or the Chrome DevTools postMessage bridge
@sh1n4ps/plasma-client-sqlite You want the sql.js / OPFS SQLite engine on the client instead of the default IndexedDB engine
Terminal window
pnpm add @sh1n4ps/plasma-devtools @sh1n4ps/plasma-client-sqlite

What each package does

Section titled “What each package does”
  • @sh1n4ps/plasma-core — pure types + schema DSL + query AST + wire protocol. Zero runtime dependencies beyond the standard library. This is what your schema.ts file imports.
  • @sh1n4ps/plasma-client — IndexedDB engine, live queries with IVM, optimistic mutate + push/pull + rebase, WebSocket subscription helper, file blob upload worker.
  • @sh1n4ps/plasma-server — SQL compiler (SQLite / Postgres dialects), sync handler, executor adapters (fromBetterSqlite3 / fromD1), SyncCoordinator Durable Object, R2 Storage adapter, blob endpoints, GC helpers, SequencerDO.
  • @sh1n4ps/plasma-react — PlasmaProvider, useLiveQuery, useMutation, usePlasmaFile. Framework-specific hooks live here; the rest is framework-agnostic.
  • @sh1n4ps/plasma-devtools — the in-page React panel, the postMessage bridge for a Chrome DevTools extension, and the reflection hooks that read plasma’s internal stores.

Verify

Section titled “Verify”
Terminal window
pnpm ls @sh1n4ps/plasma-core @sh1n4ps/plasma-client @sh1n4ps/plasma-server @sh1n4ps/plasma-react

You should see all four at the version you just installed.

Next

Section titled “Next”