{"id":16107,"library":"lowdb","title":"lowdb Local JSON Database","description":"lowdb is a lightweight, type-safe, local JSON database designed for Node.js, Electron, and browser environments. The current stable version is 7.0.1, with a frequent release cadence that has seen multiple major and minor versions released recently, indicating active development and continuous improvement. Key differentiators include its minimalist API for interacting with data using native JavaScript array methods, robust TypeScript support for data schema, and a highly extensible architecture via 'adapters'. These adapters allow for custom storage solutions (e.g., YAML, JSON5, encryption) and seamless integration across different environments (file system for Node, localStorage or sessionStorage for browsers). It is primarily an ESM-first package, simplifying usage in modern JavaScript projects but requiring specific import patterns. It also offers convenient presets for common use cases like JSON files and browser storage, alongside automatic in-memory mode for testing.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/typicode/lowdb","tags":["javascript","database","db","electron","embed","embedded","flat","JSON","local","typescript"],"install":[{"cmd":"npm install lowdb","lang":"bash","label":"npm"},{"cmd":"yarn add lowdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add lowdb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment, explicitly requires Node.js version >=18 since lowdb v7.0.0. Older Node versions are not supported.","package":"node","optional":false},{"reason":"Commonly used for extending lowdb's data querying and manipulation capabilities, as demonstrated in the official documentation examples for more complex operations.","package":"lodash","optional":true}],"imports":[{"note":"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.","wrong":"import { JSONFilePreset } from 'lowdb'","symbol":"JSONFilePreset","correct":"import { JSONFilePreset } from 'lowdb/node'"},{"note":"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)`.","wrong":"const { Low } = require('lowdb')","symbol":"Low","correct":"import { Low } from 'lowdb'"},{"note":"For browser environments, use the `lowdb/browser` subpath to access browser-specific adapters like `LocalStoragePreset`, introduced in v5.0.0.","wrong":"import { LocalStoragePreset } from 'lowdb'","symbol":"LocalStoragePreset","correct":"import { LocalStoragePreset } from 'lowdb/browser'"},{"note":"`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.","wrong":"import { JSONPreset } from 'lowdb/node'","symbol":"JSONPreset (deprecated)","correct":"import { JSONFilePreset } from 'lowdb/node'"}],"quickstart":{"code":"import { JSONFilePreset } from 'lowdb/node';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join } from 'node:path';\n\n// Resolve __dirname equivalent in ESM\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst dbFilePath = join(__dirname, 'db.json');\n\ntype Post = { id: number; title: string; views: number };\ntype Data = { posts: Post[] };\n\nasync function runDbExample() {\n  // Define default data with type safety\n  const defaultData: Data = { posts: [] };\n\n  // Initialize the database with a JSON file adapter\n  // This will create 'db.json' if it doesn't exist, populated with defaultData\n  const db = await JSONFilePreset<Data>(dbFilePath, defaultData);\n\n  // Read the current data from the file\n  await db.read();\n  console.log('Initial data:', db.data);\n\n  // Add a new post using db.update() for atomic writes and automatic saving\n  const newPost = { id: 1, title: 'lowdb is awesome', views: 100 };\n  await db.update(({ posts }) => posts.push(newPost));\n  console.log('Data after adding post:', db.data);\n\n  // Query data using native JavaScript array methods\n  const { posts } = db.data;\n  const firstPost = posts.at(0);\n  console.log('First post:', firstPost);\n\n  // Modify an existing item and explicitly save\n  if (firstPost) {\n    firstPost.views += 10; // Modify in memory\n    console.log('Modified post in memory:', firstPost);\n    await db.write(); // Explicitly write changes back to db.json\n  }\n  console.log('Final data after explicit write:', db.data);\n}\n\nrunDbExample().catch(console.error);\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Replace `JSONPreset` with `JSONFilePreset` when importing from `lowdb/node`.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js environment to version 18 or higher.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure you always pass an initial `defaultData` object as the second argument to `new Low(adapter, defaultData)`.","message":"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`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Update your import paths: `import { JSONFile } from 'lowdb/node'` for Node and `import { LocalStorage } from 'lowdb/browser'` for browsers.","message":"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`.","severity":"breaking","affected_versions":">=5.0.0"},{"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\"`.","message":"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`.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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\"`.","cause":"Attempting to use `import` statements in a CommonJS context for an ESM-only package.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Provide a default data object as the second argument: `new Low(adapter, { posts: [] })`.","cause":"Missing the `defaultData` argument when instantiating `Low` or `LowSync`.","error":"TypeError: The 'defaultData' parameter is required for Low and LowSync constructors."},{"fix":"For Node.js, use `import { JSONFile } from 'lowdb/node'`. For browsers, use `import { LocalStorage } from 'lowdb/browser'`.","cause":"Incorrect import path for Node.js or browser adapters after the v5.0.0 split.","error":"Error: Cannot find module 'lowdb/JSONFile' or 'lowdb/LocalStorage'"},{"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)`.","cause":"TypeScript compiler cannot infer the correct type of `db.data` without generic type parameters or proper default data definition.","error":"Property 'someProperty' does not exist on type '{ posts: any[]; }' (or similar TypeScript error when accessing `db.data`)"}],"ecosystem":"npm"}