Skip to content

tinyplex/tinybase / docs/skills/build-with-tinybase

build-with-tinybase

Unverified

Scaffold, extend, and verify reactive local-first JavaScript or TypeScript applications with TinyBase. Use when choosing TinyBase for in-memory tabular or key-value state, generating an app with create-tinybase, adding schemas or UI bindings, resolving TinyBase import paths, configuring browser or database persistence, configuring MergeableStore synchronization over WebSockets or Cloudflare Durable Objects, or diagnosing an existing TinyBase application.

FileKindSize
SKILL.mdskill md6.1 KB
agents/openai.yamlconfig225 B
references/architecture.mdmarkdown3.1 KB
references/durable-objects.mdmarkdown8.4 KB
references/import-paths.mdmarkdown9.6 KB
references/lifecycle.mdmarkdown8.3 KB

references/architecture.md

View on GitHub
# TinyBase Architecture Selection

## Core Decisions

| Requirement                                      | Starting point                   |
| ------------------------------------------------ | -------------------------------- |
| Reactive ephemeral application data              | Store                            |
| Deterministically mergeable or synchronized data | MergeableStore                   |
| Data surviving reloads or process restarts       | Persister                        |
| Exchange changes between Store copies            | Synchronizer with MergeableStore |
| React rendering                                  | `tinybase/ui-react`              |
| Solid rendering                                  | `tinybase/ui-solid`              |
| Svelte rendering                                 | `tinybase/ui-svelte`             |

Use Tables for collections of Rows and Cells. Use Values for independent
key-value application state. Both can coexist in one Store.

## Persistence

Choose the simplest backend satisfying the runtime and durability requirement:

- Browser Local Storage or Session Storage for small browser data.
- IndexedDB or OPFS for browser-owned durable data.
- SQLite or PGlite for relational local storage.
- Expo SQLite or React Native integrations on mobile.
- File, PostgreSQL, SQLite, or Durable Object persistence on servers.
- A third-party Persister when integrating with an existing sync platform.

Load persisted content before starting automatic saving. Otherwise initial
in-memory content can overwrite durable content during startup. Destroy or stop
resources when their owning runtime or component is torn down.

## Synchronization

Use a MergeableStore when changes from separate copies can meet. Its CRDT
metadata enables deterministic merging.

- BroadcastChannel synchronizes same-origin browser contexts.
- WebSocket synchronizers connect browsers, clients, and servers.
- Local synchronization is useful for tests and same-process setups.
- Durable Objects can combine WebSocket coordination with durable server state.

Persistence and synchronization are complementary. Persistence keeps a local or
server copy durable; synchronization exchanges changes between copies.

## Schemas

TinyBase schemas validate data at runtime and drive TypeScript inference through
`with-schemas` entry points. Add schemas when the data model is stable enough to
benefit from validation and typed identifiers. Keep defaulted fields required:
a default value supplies missing data rather than making the field optional.

## create-tinybase Mapping

Use `npm create tinybase@latest -- --list-options` as the authority for current
values. The principal choices are:

- `appType`: example application surface
- `language`: JavaScript or TypeScript
- `framework`: Vanilla JS, React, Solid, or Svelte
- `schemas`: typed Store schemas for TypeScript projects
- `syncType`: none, remote demo, local Node server, or Durable Objects
- `persistenceType`: none, Local Storage, SQLite, or PGlite

Generated projects intentionally provide complete lifecycle wiring. Prefer the
closest generated architecture, then modify application data and UI.
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall