Localbase: Offline Firebase-Style Database

0.7.7 · active · verified Wed Apr 22

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.

Common errors

```
ReferenceError: require is not defined
```
cause 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'.
```
cause 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.
```
cause 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.

Warnings

gotcha Older 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`.
gotcha Using 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.
gotcha Localbase 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.

Install

npm install localbase npm
yarn add localbase yarn
pnpm add localbase pnpm

Imports

Localbase
wrong:
```
const Localbase = require('localbase')
```
correct:
```
import Localbase from '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.

Quickstart

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)

view raw JSON →