Spinetab
Share live subscriptions across browser tabs with a SharedWorker. Spinetab manages
connection sharing, subscription cleanup and recovery, with a per-tab fallback
when sharing is unavailable. Your application keeps control of its data and cache.
Use your existing HTTP, WebSocket or protocol endpoints. Optional integrations
connect Spinetab to Apollo, TanStack Query, SWR, tRPC and AI SDK; bindings cover
React, Vue, Svelte and Solid.
Spinetab is maintained by agents
Install
pnpm add spinetab
Add the bundler plugin, create one client and subscribe. The
quick start walks through a polling feed
in an existing Vite app. See the
framework guides for Next.js,
Astro, Nuxt, SvelteKit and React Router setup.
Reconnection restores live delivery. Recovering missed events requires backend
replay or application reconciliation; there is no exactly-once delivery guarantee.
During 0.x, breaking API changes use a minor version; patch releases remain
backwards-compatible.
Repository structure
apps/website/ Astro + Starlight site: documentation and landing page
packages/spinetab/ The library: page, worker, runtime and build entries, adapters, bindings, tests
packages/typescript/ Private shared TypeScript presets
packages/spinetab/tests/fixtures/harness is a private workspace used only by the
library's browser tests. The website consumes the built package through
workspace:*, never source aliases.
Development setup
Use Node 24.11+ and pnpm 12.14.0 (pinned in package.json):
pnpm install
pnpm dev
Dependencies must support this floor. .npmrc enables engineStrict, so a
package whose engines excludes Node 24.11 makes pnpm install fail. When
updating dependencies, check the engines entries that change in pnpm-lock.yaml,
and keep @types/node on the Node 24 line so types match the oldest supported runtime.
The website runs at http://127.0.0.1:4321 (documentation under /docs/). Turbo builds the library before
starting the website and the library watcher. No environment files are required.
pnpm install also installs the repository's Git hooks.
Remote caching is optional. Run pnpm exec turbo login, then
pnpm exec turbo link to share build, typecheck and test results through your
Vercel team. Without remote authentication, Turbo uses its local cache.
Use pnpm exec turbo run e2e --force for a fresh browser run. Publication
verification bypasses cached results.
The website build generates /llms.txt, /recipe-index.md and a Markdown version
of every public page (/index.md for the homepage, /docs/setup/nextjs.md for
/docs/setup/nextjs/). The exporter uses rendered documentation and original recipe
files; edit those sources rather than maintaining separate Markdown copies.
HTML pages advertise their Markdown counterparts with rel="alternate" links.
The exporter omits aria-hidden="true" decoration and elements marked
data-markdown-exclude. Hidden documentation panels remain included.
The website E2E suite serves the build with Cloudflare Pages locally, including
the _headers rules and cache revalidation behaviour.
CI repeats the documentation HTTP checks against the deployed Pages URL.
Commands
Run from the repository root:
| Command | Purpose |
|---|
pnpm dev | Start the website and library watcher |
pnpm build | Build the library and static website |
pnpm check | Check formatting, lint and imports |
pnpm check:fix | Apply Biome's safe fixes and Prettier formatting |
pnpm format | Format code with Biome and documentation/configuration with Prettier |
pnpm typecheck | Check TypeScript and Astro |
pnpm test | Build the library and run its unit, integration, DOM and package suites |
pnpm e2e | Run the library and website browser suites |
Validation tooling in the library, run with pnpm --filter spinetab run <script>:
| Script | Purpose |
|---|
consumers:prepare | Pack the library and prepare out-of-tree consumer applications |
test:consumers | Install, build and type-check the packed package in those consumers |
e2e:consumers | Run the consumer applications in browsers |
test:tree-shaking | Verify unused-export removal and production worker retention |
perf | Run the Playwright performance scenarios |
perf:sizes, perf:aggregate and consumers:matrix summarise their results. These
scripts are not part of pnpm test or routine CI. A manually dispatched CI run
also verifies tree shaking and packed consumer applications. Run the library
build before test:tree-shaking; it packs that build and checks Vite, webpack,
Rspack and Next.js (Turbopack and webpack).
Package and toolchain PRs also run tree shaking and packed-consumer installation,
build and type checks alongside standard CI. The longer packed-consumer browser
matrix runs before publication and on manually dispatched CI runs without deployment.
Before the first browser test run:
pnpm --filter website exec playwright install
Testing
The test suites cover core behaviour, real protocol integration, framework
bindings, package exports and browser recovery. Packed consumer applications
exercise installation, bundling, SSR and lifecycle behaviour in supported
frameworks. Browser checks run in Chromium, Firefox and WebKit.
See the compatibility guide
for tested versions and known restrictions. Test fixtures live under
packages/spinetab/tests; generated reports are ignored by Git.
Continuous integration
CI runs in Microsoft's Playwright container, whose image tag matches
@playwright/test (1.64.1), as a non-root user with
PLAYWRIGHT_BROWSERS_PATH=/ms-playwright:
pnpm install --frozen-lockfile
pnpm exec biome ci .
pnpm exec prettier --check .
pnpm exec turbo run typecheck test e2e
Keep the image tag, the @playwright/test versions and the browser path aligned
when upgrading Playwright. CI uploads the library's and the website's Playwright HTML
reports as artefacts, and the raw test output when a run fails.
Contributing
- Biome formats and lints code, including package manifests. Astro support is
experimental;
astro check supplies additional diagnostics.
- Prettier formats Markdown, MDX and YAML only.
.prettierignore keeps its scope
separate from Biome and excludes generated files and the lockfile.
- Commit the pnpm lockfile. CI installs with
--frozen-lockfile.
- Keep adapters, integrations and bindings inside the single library package, each
behind its own subpath. Pin each optional peer range to the version it is tested
against.
- Run
pnpm check and pnpm exec turbo run typecheck test e2e before opening a
pull request. CI enforces them.
- Pre-commit formats and lints staged files. Pre-push checks formatting and lint,
then builds, type-checks and tests the workspace. Browser E2E runs in CI.
Application state, caches, backend replay and server helpers are outside the
library's scope.
