Ikago

A lightweight IndexedDB wrapper with React hooks for building client-side databases with live queries in React.

Ikago provides:

Easy IndexedDB management with schema definitions

CRUD operations (add, update, delete, find, populate)

React hooks: useCollection, useLiveQuery, and useIkago

BroadcastChannel support for live updates across tabs

Fully typed for TypeScript projects

Table of Contents

Installation

Quick Start

Database API

Store API

React Hooks

TypeScript Support

Examples

License

Installation npm install ikago

Peer dependencies:

npm install react react-dom

Quick Start

import { IkagoProvider, useCollection, useLiveQuery } from "ikago";

function Users() {
  const users = useCollection("users"); 
  const adults = useLiveQuery("users", { age: { $gte: 18 } });

  if (!users) return <p>Loading DB...</p>;

  const addUser = async () => {
    await users.add({
      name: "Ravi",
      email: Math.random() + "@mail.com",
      age: 22
    });
  };

  return (
    <div>
      <h1>Ikago + React</h1>
      <button onClick={addUser}>Add User</button>
      <ul>
        {adults.map(u => (
          <li key={u.id}>
            {u.name} ({u.age})
          </li>
        ))}
      </ul>
    </div>
  );
}

export default function App() {
  return (
    <IkagoProvider
      dbName="ikago-demo"
      version={1}
      schema={{
        users: {
          keyPath: "id",
          autoIncrement: true,
          fields: {
            name: { required: true },
            email: { unique: true },
            age: {}
          }
        }
      }}
    >
      <Users />
    </IkagoProvider>
  );
} 

Database API new Database(name: string, version?: number)

Methods:

define(schema: DatabaseSchema): Database // Define schema connect(): Promise // Open database connection collection(name: string): Store // Get a store instance

Store API new Store(db: IDBDatabase, name: string, schema?: StoreSchema)

Represents a collection in the database.

Methods:

add(doc: any): Promise
addMany(docs: any[]): Promise
update(doc: any): Promise
delete(id: any): Promise
clear(): Promise
get(id: any): Promise
getAll(): Promise<any[]>
where(fn: (doc: any) => boolean): Promise<any[]> find(query?: Record<string, any>): Promise<any[]> byIndex(index: string, value: any): Promise
populate(field: string, targetStoreName: string, options?: { as?: string }): Promise<any[]>

React Hooks IkagoProvider

Wrap your React app to provide the database context:

<IkagoProvider dbName="my-db" version={1} schema={{ users: { ... } }}>
  <App />
</IkagoProvider>

useIkago()

Get the database instance inside components:

const db = useIkago();

useCollection(name: string)

Get a store instance for CRUD operations:

const users = useCollection("users"); await users.add({ name: "Ravi" });

useLiveQuery(storeName: string, query?: object)

Get live-updating query results:

const adults = useLiveQuery("users", { age: { $gte: 18 } });

TypeScript Support

Ikago ships with type declarations. Import and use with full type safety:

import { Database, Store, IkagoProvider, useCollection } from "ikago";

const db: Database = new Database("test").define({ users: { keyPath: "id", autoIncrement: true, fields: { name: {} } } });

Examples

Adding Data

await users.add({ name: "Alice", email: "[email protected]", age: 25 });

Querying Data

const adults = await users.find({ age: { $gte: 18 } });

Populating References

const postsWithAuthors = await posts.populate("authorId", "users", { as: "author" });

Live Queries in React

const adults = useLiveQuery("users", { age: { $gte: 18 } });

License

MIT License © 2026