2 min read
Local-First Data
Claude sometimes overcomplicates data storage — suggesting databases or cloud services when localStorage or UserDefaults would work fine. This skill file keeps things simple and local.
Filename: local-first.md
The Skill File
Copy this into a file called local-first.md in your project root, next to your CLAUDE.md.
# Local-First Data Conventions
Follow these conventions for all data storage in this project. Keep data local unless the user explicitly asks for sync or cloud storage.
## Storage Decision
- Simple settings/preferences → UserDefaults (macOS/iOS) or localStorage (web)
- Structured data with multiple properties → SwiftData (macOS/iOS) or localStorage with JSON (web)
- Large files or blobs → FileManager (macOS/iOS) or IndexedDB (web)
- Do NOT suggest Firebase, Supabase, or any cloud database unless the user specifically asks for sync
## Web: localStorage Patterns
- Wrap in try/catch (private browsing can throw)
- JSON.stringify before saving, JSON.parse when loading
- Use a consistent key naming pattern: appName_dataType (e.g., "weather_favorites")
- Check for existing data on page load; provide defaults if empty
- Auto-save on change, not on a timer
## macOS/iOS: UserDefaults Patterns
- Use @AppStorage for SwiftUI bindings to simple values
- Good for: booleans, strings, numbers, small arrays
- Not good for: complex objects, large datasets, images
## macOS/iOS: SwiftData Patterns
- Use @Model for data classes
- Keep models simple — properties, not methods
- Use @Query in views to fetch data
- Relationships are fine but keep them shallow
- Let SwiftData auto-save (don't call save() manually unless needed)
## First Launch
- Always handle the empty state — what does the user see before adding data?
- Pre-populate with example data if it helps the user understand the app
- Show a helpful message, not a blank screen
## Data Migration
- When adding new properties to a model, provide default values
- Don't delete old data — migrate it
- Keep a version number in saved data if the schema might changeWhen to Use This
Add this to any project that saves data — habit trackers, note apps, weather favorites, mood boards. Keeps Claude from suggesting cloud databases when local storage is all you need.