WatermelonDB Offline Storage on iOS via Claude Prompts

When a React Native app needs to work offline with real data, not just a few saved settings, WatermelonDB is the usual answer. It is a reactive database built on SQLite, made for apps with thousands of records that must stay fast and keep working with no connection. You can structure the whole thing through Claude prompts, as long as you understand which parts Claude can decide and which parts you must. Here is how to lay it out and what to ask for. Start the UI from a free VP0 design (the free iOS and React Native design library AI builders read from) at $0.

When to reach for it

WatermelonDB is not for a handful of toggles; AsyncStorage covers that. It earns its place when you have a real local dataset and want the UI to update automatically as data changes.

Storage	Good for	Not for
AsyncStorage	A few key-value settings	Large or relational data
SQLite (raw)	Structured local data	Reactive UI without extra work
WatermelonDB	Thousands of records, offline-first, observable	Tiny apps where it is overkill

Because it is built on SQLite and lazy by default, it stays fast as the dataset grows, which is the whole point.

The three parts to structure

A WatermelonDB setup is a schema, models, and queries. The schema declares tables and columns. The model classes map to those tables with decorators for fields and relations. The queries are observable, so when you subscribe in a component, the UI re-renders as data changes. Writes happen inside a writer block so changes are atomic. Claude is good at scaffolding all three from a clear description: “Here are my entities and their fields and relations, generate the WatermelonDB schema, model classes, and the observable queries for the list and detail screens.” The docs at watermelondb.dev are the reference to check the generated decorators against. This pairs naturally with the WatermelonDB offline app sync in React Native and the broader local-first offline UI templates.

Sync is yours, not Claude’s

Here is the line. Claude can scaffold the synchronize call and the shape of the pull and push handlers, but it cannot design your sync protocol: which endpoint returns changes since a timestamp, how you mark created, updated, and deleted records, and how conflicts resolve. That is a contract between client and server, and getting it wrong corrupts data quietly. Treat the generated sync as a skeleton you complete and test against your real backend. While building, give offline its own UI with the offline-mode empty state, and remember that, like Mapbox in Mapbox navigation in React Native, WatermelonDB uses native code (JSI) and needs a dev build, not Expo Go. Once the data layer is solid, screens like a Pix payment QR code screen can read and write through the same models.

Key takeaways

• WatermelonDB is a reactive, SQLite-backed database for offline-first apps with large datasets.
• Structure it as schema, model classes, and observable queries; writes go in a writer block.
• Claude can scaffold the schema, models, and queries from a clear data description.
• You must design the sync protocol and conflict rules; treat generated sync as a skeleton.
• It needs a native dev build (JSI), not Expo Go; start the UI from a free VP0 design at $0.

Frequently asked questions

What is WatermelonDB and when should I use it?

WatermelonDB is a reactive database for React Native built on top of SQLite, designed for offline-first apps with large datasets (thousands of records) that need to stay fast. Use it when AsyncStorage is too small and slow and you want observable queries that update the UI automatically. For a handful of key-value settings it is overkill; for a real local dataset it shines.

How do I structure a WatermelonDB database?

Three parts: a schema that declares tables and columns, model classes that map to those tables with decorators for fields and relations, and observable queries you subscribe to in the UI. Writes happen inside a writer block. Claude can scaffold the schema, the models, and the queries from a clear description of your data.

Can Claude set up WatermelonDB sync for me?

Claude can scaffold the synchronize call and the shape of the pull and push handlers, but you must design the actual sync protocol: which endpoints return changes, how you timestamp them, and how conflicts resolve. Sync is a backend contract, not just client code, so treat the generated sync as a starting skeleton you complete and test against your server. On the native-Apple stack, the same schema-in-models-out prompting drives the Core Data to SwiftData migration.

Does WatermelonDB work in Expo Go?

Not in Expo Go. WatermelonDB uses JSI and native code, so you need a custom development build (a dev client) rather than Expo Go. Prompt Claude for the schema, models, and queries, but plan to build a dev client to actually run it on a device or simulator.

What is the best way to build an offline-first iOS app with WatermelonDB?

Let Claude scaffold the schema, models, and observable queries, design your sync protocol deliberately, and start the UI from a clean layout. A free VP0 design, the free iOS and React Native design library for AI builders, gives you the list and detail screens to bind to WatermelonDB queries and generate in Cursor or Claude Code at $0.