# NitromelonDB > NitromelonDB (npm: `nitromelondb`) is a reactive, lazy-loading SQLite database for React Native, web, Node.js and Electron. It's a maintained fork of WatermelonDB with the same model: schema, `Model` classes with decorators, observable queries, and offline-first sync with your own backend. Native SQLite runs through Nitro Modules on the React Native New Architecture. Things to get right when writing code with NitromelonDB: - Import from `nitromelondb` (`nitromelondb/decorators`, `nitromelondb/hooks`, `nitromelondb/adapters/sqlite`), not `@nozbe/watermelondb`. Existing WatermelonDB schemas, models and SQLite files keep working; see Migrating from WatermelonDB. - React Native New Architecture only (RN 0.83+). Expo is supported through the `nitromelondb` config plugin in development builds and EAS; Expo Go is not. - Models use legacy decorators: `@babel/plugin-proposal-decorators` with `{ legacy: true }`. - Every create, update and delete must run inside a writer: `database.write(async () => ...)` or a `@writer` method on a model. - Don't call `database.write()` / `database.read()` (or a `@writer` / `@reader` method) from inside another writer or reader and wait for it; that deadlocks. Use `writer.callWriter(() => ...)` / `reader.callReader(() => ...)`. Pass `experimentalDetectNestedWriters: __DEV__` to `new Database()` to turn the mistake into an error during development. - For UI, observe instead of fetching once: `withObservables` or the hooks in `nitromelondb/hooks` (`useQuery`, `useRecord`, `useWriter`). - For whole jobs, use the agent skills in the repository's `skills/` folder (`npx skills add StasDoskalenko/NitromelonDB`): `nitromelondb-install` (a new install: packages, platform setup, schema, models, Database and a data layer on hooks), `nitromelondb-schema` (design the schema, and every later change with its migration), `nitromelondb-sync` (backend endpoints and the app's sync engine), `nitromelondb-migrate-from-watermelondb`, `nitromelondb-migrate-decorators`, `nitromelondb-audit` (setup gaps and misuse) and `nitromelondb-indexes` (missing indexes, with the migration). See Agent skills. For writing app code by hand, follow Performance: Building a fast app. - Each link below points to a plain Markdown version of the page. `llms-full.txt` next to this file has the full text of every page except the Optional section. ---

NitromelonDB

A reactive, offline-first SQLite database for React Native, Expo, the web, Windows and Node.
A maintained fork of WatermelonDB, on the React Native New Architecture.

MIT License npm Discord

Documentation · Installation · Migrating from WatermelonDB · Performance · Discord

NitromelonDB keeps your data in SQLite and loads only what a screen asks for, so apps with tens of thousands of records still launch fast. Records are observable: change one, and every component that shows it re-renders. It syncs with your own backend. It continues [WatermelonDB](https://github.com/Nozbe/WatermelonDB) by [Nozbe](https://github.com/Nozbe), which hasn't kept up with React Native, iOS and Android for a while. Models, queries, writers and sync work the same way, and existing databases keep working. Coming from `@nozbe/watermelondb`? Follow the [migration guide](https://stasdoskalenko.github.io/NitromelonDB/docs/Migrating). (The original WatermelonDB introduction now lives in [LEGACY_README.md](https://github.com/StasDoskalenko/NitromelonDB/blob/master/LEGACY_README.md).) ## Install **With a coding agent** (Claude Code, Cursor, Codex and others). From the root of your app: ```bash npx skills add StasDoskalenko/NitromelonDB --skill nitromelondb-install ``` Then ask your agent to add NitromelonDB to the app, or run `/nitromelondb-install`. It checks the requirements, installs the packages, sets up decorators and the Expo plugin for your platform, designs the schema with you, writes the models, the database and a data layer on hooks, and checks the build. Coming from `@nozbe/watermelondb`, use `--skill nitromelondb-migrate-from-watermelondb` instead. There are also skills for schema changes, sync, audits and indexes: [Agent skills](https://stasdoskalenko.github.io/NitromelonDB/docs/AgentSkills). **By hand:** ```bash # Expo (development build, EAS Build or EAS Update; not Expo Go) npx expo install nitromelondb react-native-nitro-modules # bare React Native yarn add nitromelondb react-native-nitro-modules ``` Expo apps also add `"nitromelondb"` to `plugins` in `app.json`. Expo needs no Babel setup for decorators; bare React Native needs four Babel plugins. Then rebuild the native app. All steps, per platform: [Installation](https://stasdoskalenko.github.io/NitromelonDB/docs/Installation). **Requirements:** React Native 0.83+ on the New Architecture, iOS 15.1+, Android minSdk 24, React Native Windows 0.84+, Node.js 22+ (for Node, Electron and tooling). For anything else, point your agent at [llms.txt](https://stasdoskalenko.github.io/NitromelonDB/llms.txt) (an index of the docs as Markdown) or [llms-full.txt](https://stasdoskalenko.github.io/NitromelonDB/llms-full.txt) (all of it in one file). ## A quick look Define models for the tables in your schema: ```ts import { Model, Query } from 'nitromelondb' import { children, field, text } from 'nitromelondb/decorators' class Post extends Model { static table = 'posts' static associations = { comments: { type: 'has_many', foreignKey: 'post_id' }, } as const @text('title') title!: string @field('is_pinned') isPinned!: boolean @children('comments') comments!: Query } ``` Then use them in components. They re-render when the data changes, wherever the change came from: ```tsx import { useQuery, useRecord, useWriter } from 'nitromelondb/hooks' function PostScreen({ post }: { post: Post }) { useRecord(post) // re-render when the post changes const comments = useQuery(post.comments) // ...or when its comments do const [togglePin, { isPending }] = useWriter(post, async (p) => { await p.update((record) => { record.isPinned = !record.isPinned }) }) return ( {post.title}