{"id":16425,"library":"localbase","title":"Localbase: Offline Firebase-Style Database","description":"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.","status":"active","version":"0.7.7","language":"javascript","source_language":"en","source_url":"https://github.com/dannyconnell/localbase","tags":["javascript","database","offline","firebase","firestore","indexeddb","typescript"],"install":[{"cmd":"npm install localbase","lang":"bash","label":"npm"},{"cmd":"yarn add localbase","lang":"bash","label":"yarn"},{"cmd":"pnpm add localbase","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Localbase is built on top of LocalForage for IndexedDB abstraction.","package":"localforage","optional":false}],"imports":[{"note":"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.","wrong":"const Localbase = require('localbase')","symbol":"Localbase","correct":"import Localbase from 'localbase'"},{"note":"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.","symbol":"Localbase (TypeScript type)","correct":"import Localbase from 'localbase'\n// ... then use 'new Localbase()' which provides type inference ..."}],"quickstart":{"code":"import Localbase from 'localbase'\n\nconst db = new Localbase('my-app-db')\n\nasync function manageData() {\n  // Add a document\n  await db.collection('users').add({\n    id: 'user123',\n    name: 'Alice',\n    email: 'alice@example.com'\n  })\n  console.log('Added Alice.')\n\n  // Update a document\n  await db.collection('users').doc('user123').update({\n    email: 'alice.updated@example.com'\n  })\n  console.log('Updated Alice\\'s email.')\n\n  // Get all documents in a collection\n  const users = await db.collection('users').get()\n  console.log('Current users:', users)\n\n  // Get a specific document\n  const alice = await db.collection('users').doc('user123').get()\n  console.log('Alice data:', alice)\n}\n\nmanageData().catch(console.error)","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade to `localbase@^0.7.6` or later: `npm install localbase@latest`.","message":"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.","severity":"gotcha","affected_versions":"<0.7.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always `await` Localbase operations in an `async` function, or chain with `.then()` and `.catch()` for proper control flow and error handling.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade Localbase to version 0.7.6 or newer (`npm install localbase@latest`) and ensure you are using ESM `import Localbase from 'localbase'`.","cause":"Using CommonJS `require()` syntax in a pure ESM environment (e.g., Vite, modern Node.js modules) with an older version of Localbase.","error":"ReferenceError: require is not defined"},{"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).","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.","error":"Property 'collection' does not exist on type 'Localbase'."},{"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.","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).","error":"Data not persisting/appearing after page refresh."}],"ecosystem":"npm"}