Guide · Open source

How to use lowdb: install, read and write JSON data

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

lowdb is a small JavaScript library that stores your data in a plain JSON file and lets you change it with ordinary objects and array methods. It is an npm package that runs inside a Node.js project. This guide shows you how to install it, create and update a db.json file, query the data, and decide whether it fits your job.

lowdbtypicode/lowdb · ★ 22.6k · MIT Install options & downloads

Quick start

1Install the package. Run npm install lowdb in your Node.js project folder.
2Open or create db.json. Call JSONFilePreset with the file name and default data, importing from lowdb/node.
3Change the data. Push or edit objects inside db.data using normal JavaScript.
4Save the change. Call await db.write(), or use await db.update() to change and save in one step.
5Query with Array methods. Use at, filter, find or toSorted on your arrays in db.data.

Install lowdb in a Node.js project

lowdb is installed from npm, so you need Node.js and a project that uses npm. Run the install command in your project folder.

Prerequisite: Node.js
The package is published on npm under the name lowdb

npm install lowdb

Create or open a db.json file

Use JSONFilePreset to read db.json, or create it with your default data if it does not exist yet. The file is imported from the lowdb/node entry point. lowdb is a pure ESM package, so use import syntax and top-level await as in the examples.

import { JSONFilePreset } from 'lowdb/node'

const defaultData = { posts: [] }
const db = await JSONFilePreset('db.json', defaultData)

Change data and save it to disk

Your data lives in db.data, which is a plain JavaScript object. You can change it directly and then call db.write(), or make the change and save it in one call with db.update(). Either way, lowdb writes the result to db.json.

After a write, db.json holds the updated content. In this example the file would contain one post in the posts array.

Two steps: change db.data, then await db.write()
One step: await db.update() with a function that changes the data

const post = { id: 1, title: 'lowdb is awesome', views: 100 }

// In two steps
db.data.posts.push(post)
await db.write()

// Or in one
await db.update(({ posts }) => posts.push(post))

Query data with native Array methods

You do not learn a query language. Read from db.data and use the Array functions JavaScript already provides. The README's examples cover reading the first item, filtering, finding by id and sorting.

posts.at(0) returns the first post
posts.filter(...) filters by a condition such as title
posts.find(...) finds a post by id
posts.toSorted(...) sorts by a field such as views

const { posts } = db.data

posts.at(0)
posts.filter((post) => post.title.includes('lowdb'))
posts.find((post) => post.id === 1)
posts.toSorted((a, b) => a.views - b.views)

Use TypeScript types and in-memory mode for tests

You can declare a type for your data so TypeScript checks what you push into it. The README also says lowdb automatically switches to a fast in-memory mode during tests, and it provides Memory and MemorySync adapters for unit tests.

Declare a Data type and pass it to JSONPreset to catch wrong types
Use Memory or MemorySync adapters to keep unit tests fast
Browser storage is available through LocalStorage and SessionStorage in lowdb/browser

type Data = {
  messages: string[]
}

const defaultData: Data = { messages: [] }
const db = await JSONPreset<Data>('db.json', defaultData)

What people use it for

A small command-line tool that keeps a list of items in a JSON file
A prototype web or Node.js app that needs persistent data without a database server
A unit test suite that uses the Memory adapter as a fast store
A personal script that tracks records and sorts or filters them with Array methods

Frequently asked questions

Is lowdb free to use?

lowdb is released under the MIT licence, according to the project's listing. Check the LICENSE file in the repository for the full terms before you use it in a product.

What do I need to run lowdb?

The source lists Node.js as the prerequisite and npm install lowdb as the install method. The examples use ES module import syntax and top-level await, since lowdb is a pure ESM package.

Can lowdb handle large datasets?

The README says lowdb is not a fit for large datasets or heavy concurrent writes, because data lives in one JSON file. It also says lowdb does not support Node's cluster module, and that large JavaScript objects can hit performance limits.

Does lowdb support indexes, transactions or multiple clients?

The README does not describe these features. For projects that need a real database server with multiple clients, indexes or transactions, the source suggests choosing a different tool.

What are alternatives to lowdb?

The project's comparable projects are NeDB, PouchDB, SQLite through better-sqlite3, and Keyv. Pick based on whether you need a file-based JSON store, a sync-capable database, a SQL engine or a key-value cache.

Can I store data in a format other than JSON?

Yes. The README shows a custom adapter built on TextFile that reads and writes YAML with the yaml package. You can also use DataFile with other parse and stringify functions, for example to add encryption.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

lowdb suits Node.js developers who want simple persistent storage for small tools, prototypes or tests, and who like working with plain JavaScript arrays. If you have large datasets, many concurrent writers, or need indexes or transactions, choose a real database server or a tool such as SQLite instead.

Install options & downloads