npm i oncilla


Client-side database for real-time and optimistic UI

by TheoremOne

5.5.0 (see all)License:ISCTypeScript:Not Found
npm i oncilla

Oncilla logo

Client-side database for easy to implement real-time and optimistic UI.

ISC license npm version npm bundle size Unpolished

Oncilla DB sits between your UI logic (i.e. React components) and your server and synchronizes the data between the two. It rerenders your views when new data arrives, and sends updates to the server in the background, allowing your UI to stay responsive. No matter what happens, whether errors or network connectivity issues arise, Oncilla will work to keep the data between your UI and the server in sync.

Diagram: Oncilla sits between React/Vue.js/Angular and a server database

Great developer experience. Oncilla DB takes on complexity so that your code is as simple as possible. In React components, accessing and changing the data is synchronous and almost as easy as React’s useState. Features like prefetching, real-time updates, optimistic UI become trivial to enable.

Great user experience. Oncilla DB also takes on complexity so that you need not choose between your velocity and the user experience. Great user experience is the default.

Wide flexibility. You can use Oncilla DB with any view and persistence tooling you want. It comes at a cost of a bit more initial configuration, but that is something you setup once and forget. At the moment the primary supported tooling is React for the view and WebSockets for the server, and you still need to implement your database queries.

Stable, but unpolished. Oncilla DB is stable and used in production. That said, it’s a passion project limited by practicality, so many corners are as of yet unpolished, expect to contribute whenever you hit some corner cases or find missing advanced functionality.

Requires specific data modeling. Your data will have to be modeled in terms of kind-id entities, and those entities will always be edited, synced, and accessed atomically, in full. If you can’t identify clearly delineated entities, if your entities can’t be split into chunks we can download all at once, or if you need to control user access to individual subpieces of an entity, using Oncilla will require considerable workarounds.


See the setup guide for initial configuration.

Access and modify data with Oncilla with synchronous access.

const [task, updateTask] = useData("tasks", taskId);
if (task === "loading") return <Spinner />;
return (
      onChange={(e) => updateTask("title", e.target.value)}

// For simple field updates use the simple form like above, but when the update you perform is more complex, use a delta function form:
// updateTask(prevTask => ({ ...prevTask, title: prevTask + " appended" }))

// Prefer multiple useData calls above, but when the data you need to fetch is dynamic in its length, useMultipleData can help:
const [tasks, update] = useMultipleData("tasks", ["1", "3"]);
console.log(tasks["1"], tasks["3"]);
update("3", (prev) => ({ ...prev, title: "new title" }));

A preview of how you access the information about the status of the synchronization, like whether the user is offline and whether any changes are not saved yet:

const connectivity = useConnectivity();
return (
    {connectivity === "offline" && <div>Offline. Changes will be saved when you go online.</div>}
    <MyView />


Oncilla DB has been heavily inspired by PouchDB, CouchDB, and the Offline First thinking.

PouchDB brings a lot of battle-tested power to the table, but it relies on the CouchDB protocol for replication. Oncilla allows you to define your own replication protocol that will fit your API, or use a small Oncilla WebSocket protocol that is easy to implement in whichever backend.

Oncilla is in essence GraphQL live queries with no or very limited data dependencies, and a client-side oriented source of truth. For a more powerful approach with GraphQL live queries, see the discussion on the spec and a good introductory video.

Other projects of interest: Falcor, upcoming Apollo Client 3.

About Theorem


This software is lovingly maintained and funded by Theorem. From whiteboarding new concepts to long-term support, Theorem works with startups and large multi-national enterprises to develop new applications, software, services, and platforms to achieve the best results and deliver Full Stack Innovation™

At Theorem we believe in and support open-source software.

Theorem and the Theorem logo are trademarks or registered trademarks of Theorem, LLC.

The oncilla is a small tiger cat on the IUCN Red List.

Photo of an Oncilla



GitHub Stars



NaNyrs ago








2yrs ago
No alternatives found
No tutorials found
Add a tutorial