localbase

library0.7.7jsnpmunverified

Localbase is a JavaScript library providing a Firebase Cloud Firestore-like API for an offline, browser-based database powered by IndexedDB. It simplifies local data persistence, allowing developers to manage data in collections and documents without direct interaction with the complexities of IndexedDB. The current stable version is 0.7.7. Releases appear somewhat irregularly, primarily addressing bug fixes, compatibility issues (e.g., Vite environment), and new features like collection filtering. Its key differentiators include its familiar API for developers accustomed to Firebase, robust offline capabilities, and its foundation on LocalForage, which handles cross-browser IndexedDB inconsistencies. It also ships with TypeScript type definitions for improved developer experience.

database

npm install localbase

github ↗package ↗

INSTALL

IMPORT

SIG · LOCALBASE

localbase

databasejavascriptv0.7.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Localbase

✓ import Localbase from 'localbase'

✗ const Localbase = require('localbase')

While CommonJS `require` might work in some environments, ESM `import` is the recommended and best-supported way to use Localbase, especially with bundlers like Vite where `require` caused issues fixed in recent versions.

Localbase (TypeScript type)

✓ import Localbase from 'localbase' // ... then use 'new Localbase()' which provides type inference ...

The library ships with TypeScript types. The main class `Localbase` is imported as a default export, and its methods are then accessible and type-checked.

This quickstart demonstrates how to initialize Localbase, add a new document to a collection, update an existing document, and retrieve data from a collection and a specific document using async/await.

import Localbase from 'localbase' const db = new Localbase('my-app-db') async function manageData() { // Add a document await db.collection('users').add({ id: 'user123', name: 'Alice', email: 'alice@example.com' }) console.log('Added Alice.') // Update a document await db.collection('users').doc('user123').update({ email: 'alice.updated@example.com' }) console.log('Updated Alice\'s email.') // Get all documents in a collection const users = await db.collection('users').get() console.log('Current users:', users) // Get a specific document const alice = await db.collection('users').doc('user123').get() console.log('Alice data:', alice) } manageData().catch(console.error)

Debug

Known issues

gotchaOlder versions of Localbase (pre-0.7.6) encountered 'require is not defined' errors in modern ESM environments like Vite. Ensure you are on version 0.7.6 or newer for better compatibility with such bundlers.

fix

Upgrade to `localbase@^0.7.6` or later: `npm install localbase@latest`.

affects: <0.7.6

gotchaUsing the `.set()` method on a collection or document will overwrite all existing data at that path. Be careful when using `.set()` if you intend to merge or partially update data, as it performs a full replacement.

fix

Use `.add()` to insert new documents or `.update()` to partially modify existing documents. Only use `.set()` when you explicitly want to replace the entire document or collection.

affects: >=0.1.0

gotchaLocalbase operations are asynchronous and return Promises. Forgetting to `await` or chain with `.then()` can lead to race conditions where subsequent operations execute before data is persisted or retrieved, resulting in stale or incorrect data.

fix

Always `await` Localbase operations in an `async` function, or chain with `.then()` and `.catch()` for proper control flow and error handling.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Using CommonJS `require()` syntax in a pure ESM environment (e.g., Vite, modern Node.js modules) with an older version of Localbase.

fix

Upgrade Localbase to version 0.7.6 or newer (`npm install localbase@latest`) and ensure you are using ESM `import Localbase from 'localbase'`.

Property 'collection' does not exist on type 'Localbase'.

TypeScript compiler error, usually indicating that the `Localbase` instance is not correctly typed or the type definitions are not being picked up by the project.

fix

Ensure `localbase` is correctly imported as a default export (`import Localbase from 'localbase'`). Verify `tsconfig.json` includes `"dom"` in `lib` and `"node_modules/@types"` in `typeRoots` or that `@types/localbase` is not conflicting (though localbase ships its own types).

Data not persisting/appearing after page refresh.

Asynchronous operations not being correctly awaited, leading to data not being saved to IndexedDB before a page unload, or incorrect usage of the API (e.g., trying to read data before it's written).

fix

Always use `await` with Localbase operations or chain with `.then()` to ensure data operations complete before any dependent actions or page navigations occur. Verify the browser's IndexedDB for your application to confirm data is written.

Upgrade

Version history

0.7.7latest on npm

Audit

Dependencies

localforagerequiredLocalbase is built on top of LocalForage for IndexedDB abstraction.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/dannyconnell/localbase ↗

packagehttps://www.npmjs.com/package/localbase ↗