local-first
Local-first architecture decision framework for web applications. Covers when to go local-first vs server-based vs hybrid, sync engine selection (ElectricSQL, Zero, PowerSync, Replicache, LiveStore, Triplit), client-side storage options (IndexedDB, OPFS, SQLite WASM, PGlite), and conflict resolution strategies (LWW, CRDTs, server-wins, field-level merge). Use when deciding whether to adopt local-first architecture, choosing a sync engine, selecting client storage, or designing conflict resolution strategies.
- Installs
- 159
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oakoss/agent-skills --skill local-first- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads local-first automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 -yIf 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 -yIf 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
FAQ
What does the local-first skill do?
Local-first architecture decision framework for web applications. Covers when to go local-first vs server-based vs hybrid, sync engine selection (ElectricSQL, Zero, PowerSync, Replicache, LiveStore, Triplit), client-side storage options (IndexedDB, OPFS, SQLite WASM, PGlite), and conflict resolution strategies (LWW, CRDTs, server-wins, field-level merge). Use when deciding whether to adopt local-first architecture, choosing a sync engine, selecting client storage, or designing conflict resolution strategies.
How do I install local-first?
Run npx skills add https://github.com/oakoss/agent-skills --skill local-first in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/local-first/ (personal) or .claude/skills/local-first/ (project).
Which AI agents can use local-first?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is local-first safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains local-first?
It is published by oakoss in oakoss/agent-skills. It has 159 recorded installs.
More from oakoss/agent-skills
ui-ux-polish
oakoss/agent-skills
Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.
playwright
oakoss/agent-skills
Open the skill to read its SKILL.md instructions.
coolify
oakoss/agent-skills
Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration. Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
application-security
oakoss/agent-skills
Application security covering threat modeling (STRIDE), OWASP Top 10 (2025), OWASP API Security Top 10 (2023), secure coding review, authentication/authorization patterns, input validation, encryption, security headers, supply chain security, compliance (GDPR/HIPAA/SOC2/PCI-DSS), and security monitoring. Use when reviewing code for vulnerabilities, implementing auth patterns, securing APIs, configuring security headers, hardening supply chain, preventing injection attacks, or preparing for compliance audits.
find-skills
oakoss/agent-skills
Discovers and installs agent skills from the open ecosystem. Enriches search results with descriptions fetched from skills.sh. Use when a user asks "how do I do X", "find a skill for X", "is there a skill that can...", or wants to extend agent capabilities. Use for skill discovery, skill search, skill install, finding tools.
drizzle-orm
oakoss/agent-skills
Open the skill to read its SKILL.md instructions.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.