prisma-idb lets you query IndexedDB, the browser's built-in database, with the same API as Prisma Client. Your Prisma schema defines the models, and the client runs entirely in the browser. An optional sync layer sends local changes to your server and pulls back changes from other devices.
const posts = await idb.post.findMany({
where: { authorId: userId, published: true },
include: { comments: { orderBy: { createdAt: "desc" } } },
orderBy: { createdAt: "desc" },
});
This page explains why prisma-idb exists and how it is designed. To install and use it, see the quick start on prisma-idb.dev, or try the offline-first kanban demo.
Why I built it
MyFit had no offline support, and I wanted to add it.
The browser already has a transactional database, IndexedDB, but its API is low-level. A query across related records means manual index lookups, joins written in application code, and no generated types. The idb wrapper library makes the calls nicer but does not change that. In Prisma, the same query is one call.
I wanted MyFit's offline code to look like its server code. prisma-idb is the library that makes that possible.
Two implementations
The repository holds two versions of the same idea.
- The generator (stable). A Prisma generator runs during
prisma generate. This one reads the schema and writes a typed IndexedDB client into your project. It supports Prisma 6 and 7, and is published as@prisma-idb/idb-client-generator. - The Prisma 8 extension (preview). Prisma 8 lets third parties add new databases through a driver, an adapter and a target. This version plugs IndexedDB into Prisma 8 that way, and is published as
@prisma-idb/client-idbplus sync packages.
Prisma's ORM manifesto names prisma-idb as one of two standout examples of Prisma 8 extensions.
Why the Prisma 8 version exists: migrations
The hardest problem was not query support. It was schema migrations.
IndexedDB changes its stores and indexes only during a versioned upgrade. A migration system for it has to track schema versions, compute the difference between them, and replay the steps in the browser. I tried to design one for the generator and could not make it complete or correct enough. It would have been a large, separate system.
Prisma 8 solves most of this. It describes the data model as a contract with a storage hash. At runtime, it compares that hash with the schema the database actually has. Migrations are edges in a graph between contracts. The Prisma 8 version of prisma-idb uses this directly:
- The build bundles the contracts into the app.
- Each migration operation translates to IndexedDB operations.
- The sync layer is a Prisma 8 extension rather than generated code.
How sync works
Sync is optional. When it is on:
- Each local write is also recorded in an outbox, a queue of pending changes, so a failed push can retry.
- The server checks each change against an ownership graph. The graph follows the schema's relations from each record back to a root model, usually
User. A change outside the caller's data is rejected. - The client pulls a changelog from the server and applies it locally. The server's version is authoritative.
Synced models use IDs generated on the client, such as cuid() or uuid(), so creating a record offline needs no server round trip.
Design decisions
The Prisma 8 version records its design in 27 architecture decision records (ADRs) in the repository. These five shaped it most.
No await inside IndexedDB transactions (ADR 005). An IndexedDB transaction commits as soon as it has no pending requests. Awaiting an unrelated promise lets it commit early, and the next request fails. The driver chains requests through callbacks instead. The cost is more verbose code and a rule the type system cannot enforce, so the tests run in real Chromium and WebKit rather than only in a simulated IndexedDB.
The client enforces foreign keys (ADR 009). IndexedDB has no foreign keys and no ON DELETE behaviour. The client checks that a parent exists on every write and runs referential actions in the same transaction. The defaults match Postgres, so a synced client and server reject the same changes.
The query planner narrows, the filter decides (ADR 021). The planner chooses a primary-key or index range to read. It may read extra rows, but it never skips a row that matches. The full filter then runs on every row read, so results are always correct. Queries that cannot use an index fall back to a full scan.
Authorization comes from the schema (ADR 014). The ownership graph used by sync is derived from the schema's relations, not from a hand-written permission list.
Rejected writes take the server's version (ADR 022). When the server permanently rejects a change, the client replaces its local row with the server's row. A CRDT (conflict-free replicated data type) would avoid some of these losses, but it would replace the relational model and its constraints. The ADR records the cost: if two offline devices create the same unique key, the second device's record disappears.
Testing
The main requirement for the tests is that every query returns the same result from prisma-idb as from Prisma Client against a real database. The generator's test app has 62 Playwright specs covering queries, filters, nested writes, relation filters and list fields. The repository has more than 250 test files in total. I wrote about the hardest part, keeping the test calls fully typed, in My best TypeScript work.
Status
- Development started in October 2024. The generator has been on npm since December 2024, and the Prisma 8 packages since September 2026.
- The Prisma 8 version stays in preview until Prisma 8 itself is generally available.
- Featured in Prisma's ORM manifesto and in Local-First News (19 November 2026).
- It is the planned data layer for the next version of MyFit.
- MIT licensed.