lowdb Local JSON Database

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` statements in a CommonJS context for an ESM-only package.
  fix Configure your project to use ES Modules. In Node.js, add `"type": "module"` to your `package.json` or rename your files to `.mjs`. If using TypeScript, ensure your `tsconfig.json` targets an appropriate module system like `"module": "NodeNext"` or `"ESNext"`.

• TypeError: The 'defaultData' parameter is required for Low and LowSync constructors.

  cause Missing the `defaultData` argument when instantiating `Low` or `LowSync`.
  fix Provide a default data object as the second argument: `new Low(adapter, { posts: [] })`.

• Error: Cannot find module 'lowdb/JSONFile' or 'lowdb/LocalStorage'

  cause Incorrect import path for Node.js or browser adapters after the v5.0.0 split.
  fix For Node.js, use `import { JSONFile } from 'lowdb/node'`. For browsers, use `import { LocalStorage } from 'lowdb/browser'`.

• Property 'someProperty' does not exist on type '{ posts: any[]; }' (or similar TypeScript error when accessing `db.data`)

  cause TypeScript compiler cannot infer the correct type of `db.data` without generic type parameters or proper default data definition.
  fix When initializing, provide a generic type to `JSONFilePreset` or `Low` to strongly type your data: `await JSONFilePreset<MyDataType>('db.json', defaultData)` or `new Low<MyDataType>(adapter, defaultData)`.

Warnings

• breaking The `JSONPreset` was superseded by `JSONFilePreset` in v7.0.0 for Node.js file storage. While `JSONPreset` might still work, `JSONFilePreset` is the recommended and future-proof way to initialize a database for JSON files.
  Fix: Replace `JSONPreset` with `JSONFilePreset` when importing from `lowdb/node`.
• breaking Node.js 14 support was dropped with the release of v6.0.0. Additionally, Node.js >=18 is now explicitly required for `lowdb` v7.0.0 and above. Running on older Node versions will result in errors.
  Fix: Upgrade your Node.js environment to version 18 or higher.
• breaking Since v6.0.0, the `Low` and `LowSync` constructors strictly require a `defaultData` parameter. This change improves TypeScript experience and prevents `db.data` from being `null` or `undefined`.
  Fix: Ensure you always pass an initial `defaultData` object as the second argument to `new Low(adapter, defaultData)`.
• breaking Beginning with v5.0.0, Node.js and browser-specific adapters were split into subpath imports. Node adapters like `JSONFile` are now found under `lowdb/node`, and browser adapters like `LocalStorage` under `lowdb/browser`.
  Fix: Update your import paths: `import { JSONFile } from 'lowdb/node'` for Node and `import { LocalStorage } from 'lowdb/browser'` for browsers.
• gotcha lowdb has been an ESM-only package since v3.0.0. Attempting to use CommonJS `require()` syntax will result in a `SyntaxError: Cannot use import statement outside a module`.
  Fix: Ensure your project is configured for ES Modules. In Node.js, add `"type": "module"` to your `package.json` or rename your files to `.mjs`. If using TypeScript, ensure your `tsconfig.json` targets an appropriate module system like `"module": "NodeNext"`.
• gotcha When modifying `db.data` directly (e.g., `db.data.posts.push(item)`), the changes are not automatically persisted to the storage. You must explicitly call `await db.write()` to save these changes. The `db.update()` method handles writing automatically.
  Fix: After any direct modification to `db.data`, ensure you call `await db.write()` to persist the changes. Alternatively, use the `await db.update((data) => { /* modify data */ })` method which automatically saves and is recommended for atomic operations.

Install

• npm install lowdb npm
• yarn add lowdb yarn
• pnpm add lowdb pnpm

Imports

• JSONFilePreset
  wrong:

  import { JSONFilePreset } from 'lowdb'

  correct:

  import { JSONFilePreset } from 'lowdb/node'

  The `lowdb/node` subpath is required for Node.js-specific adapters like `JSONFilePreset` since v5.0.0. The main 'lowdb' export does not contain it.
• Low
  wrong:

  const { Low } = require('lowdb')

  correct:

  import { Low } from 'lowdb'

  Low is the core database class. lowdb is an ESM-only package since v3.0.0, so CommonJS `require` will fail. For TypeScript, ensure you pass generic types for strong typing: `new Low<Data>(adapter, defaultData)`.
• LocalStoragePreset
  wrong:

  import { LocalStoragePreset } from 'lowdb'

  correct:

  import { LocalStoragePreset } from 'lowdb/browser'

  For browser environments, use the `lowdb/browser` subpath to access browser-specific adapters like `LocalStoragePreset`, introduced in v5.0.0.
• JSONPreset (deprecated)
  wrong:

  import { JSONPreset } from 'lowdb/node'

  correct:

  import { JSONFilePreset } from 'lowdb/node'

  `JSONPreset` was introduced in v6.1.0 but superseded by `JSONFilePreset` in v7.0.0. While it might still work, `JSONFilePreset` is the recommended and future-proof choice for Node.js file-based JSON storage.

Quickstart

Demonstrates initializing a type-safe lowdb instance with a JSON file in Node.js (ESM), adding data using `db.update`, querying data, and explicitly saving modifications made to `db.data`.

import { JSONFilePreset } from 'lowdb/node';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

// Resolve __dirname equivalent in ESM
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const dbFilePath = join(__dirname, 'db.json');

type Post = { id: number; title: string; views: number };
type Data = { posts: Post[] };

async function runDbExample() {
  // Define default data with type safety
  const defaultData: Data = { posts: [] };

  // Initialize the database with a JSON file adapter
  // This will create 'db.json' if it doesn't exist, populated with defaultData
  const db = await JSONFilePreset<Data>(dbFilePath, defaultData);

  // Read the current data from the file
  await db.read();
  console.log('Initial data:', db.data);

  // Add a new post using db.update() for atomic writes and automatic saving
  const newPost = { id: 1, title: 'lowdb is awesome', views: 100 };
  await db.update(({ posts }) => posts.push(newPost));
  console.log('Data after adding post:', db.data);

  // Query data using native JavaScript array methods
  const { posts } = db.data;
  const firstPost = posts.at(0);
  console.log('First post:', firstPost);

  // Modify an existing item and explicitly save
  if (firstPost) {
    firstPost.views += 10; // Modify in memory
    console.log('Modified post in memory:', firstPost);
    await db.write(); // Explicitly write changes back to db.json
  }
  console.log('Final data after explicit write:', db.data);
}

runDbExample().catch(console.error);