Installation
npx skills add oakoss/agent-skills --skill local-first 47
Installs
Local-First
Overview
Local-first is an architecture where the application reads and writes to a local database, with changes syncing to the server in the background. The local database is the source of truth for the UI, providing instant reads, offline support, and optimistic writes by default.
When to use: Collaborative apps needing offline support, latency-sensitive UIs where instant response matters, apps with unreliable network conditions, real-time multiplayer features, mobile apps with intermittent connectivity.
When NOT to use: Simple CRUD apps with reliable connectivity, server-authoritative workflows (payments, inventory), content-heavy sites with minimal interactivity, apps where data freshness from the server is critical on every render.
Quick Reference
| Decision | Options | Key Consideration |
|---|---|---|
| Architecture model | Server-based, local-first, hybrid | Offline needs and latency tolerance drive the choice |
| Read path | Server fetch, local DB read, cache-then-network | Local reads are instant; server reads block on network |
| Write path | Server mutation, optimistic update, local-first write | Local writes never fail; sync handles delivery |
| Sync engine | Electric, Zero, PowerSync, Replicache, LiveStore | Postgres integration vs framework-agnostic |
| Client storage | IndexedDB, OPFS, SQLite WASM, PGlite | Capacity limits, query capability, browser support |
| Conflict resolution | LWW, CRDTs, server-wins, field-level merge | Complexity vs correctness tradeoff |
| Data model | Normalized tables, document store, CRDT documents | Query patterns determine the best model |
| Partial replication | Shapes, subscriptions, query-based sync | Sync only what the client needs |
| Progressive enhancement | Server-first with local cache, full local-first | Start simple, add local-first incrementally |
| CQRS separation | Separate read/write models, unified model | Local-first naturally separates reads from writes |
| Initial sync | Full snapshot, incremental, progressive loading | First-load performance vs completeness |
| Auth integration | Token-based shape filtering, row-level security | Security lives at the sync layer, not the client |
| Schema evolution | Additive migrations, versioned shapes | Local DB schema must evolve without data loss |
| State management | Replace React Query, coexist, hybrid approach | Local-first can replace or complement server state |
| Testing strategy | Mock sync engine, test offline scenarios, seed local DB | Test both online and offline code paths |
Common Mistakes
| Mistake | Correct Approach |
|---|---|
| Going local-first for simple CRUD apps | Use server-based architecture unless offline/latency is a real need |
| Choosing a sync engine before defining data model | Define read/write patterns first, then pick the engine that fits |
| Ignoring conflict resolution until late | Design conflict strategy alongside data model from the start |
| Syncing entire database to every client | Use partial replication (shapes, subscriptions) for relevant data |
| Treating local DB as a cache | Local DB is the source of truth for the UI, not a cache layer |
| Using CRDTs for everything | LWW or server-wins is simpler and sufficient for most fields |
| Skipping progressive enhancement | Start server-first, add local-first for high-value interactions |
| Not planning schema migrations | Local databases need migration strategies just like server DBs |
Delegation
If the
electricsqlskill is available, delegate ElectricSQL setup, shapes, auth, and write patterns to it.
Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y
If therealtime-syncskill is available, delegate WebTransport, pub/sub, and CRDT implementation details to it.
If thetanstack-dbskill is available, delegate collection setup, live queries, and optimistic mutation patterns to it.
Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y
If thetanstack-startskill is available, delegate server function proxies and SSR integration to it.
Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y
- Architecture review: Use
Planagent to evaluate local-first vs server-based tradeoffs - Sync engine comparison: Use
Exploreagent to research current engine capabilities - Storage benchmarking: Use
Taskagent to test storage options for specific data patterns
References
- Architecture patterns and decision framework
- Sync engine comparison and selection guide
- Client-side storage options and limits
- Conflict resolution strategies
- Offline resilience patterns
- Schema versioning and migration
- Multi-tenant data governance patterns
- Testing strategies for local-first apps
- End-to-end encryption for synced data
- DevTools and debugging utilities
- Server-first to local-first migration guide
Installs
Security Audit
View Source
oakoss/agent-skills
More from this source
EU-Hosted Inference API Power your AI Agents with
the best open-source models.
Drop-in OpenAI-compatible API. No data leaves Europe.
Explore Inference APIGLM
GLM 5
$1.00 / $3.20
per M tokens
Kimi
Kimi K2.5
$0.60 / $2.80
per M tokens
MiniMax
MiniMax M2.5
$0.30 / $1.20
per M tokens
Qwen
Qwen3.5 122B
$0.40 / $3.00
per M tokens
How to use this skill
Install local-first by running npx skills add oakoss/agent-skills --skill local-first in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.
No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.
The skill enhances your agent's understanding of local-first, helping it follow established patterns, avoid common mistakes, and produce production-ready output.
What you get
Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.
Compatibility
This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.
Made in Europe Chat with 100+ AI Models in one App.
Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.
