Couchbase Lite for JavaScript

This is the JavaScript (really TypeScript) implementation of Couchbase Lite.

It's intended for use in web browsers.

Server and CLI environments like Node.js, Deno and Bun are not officially supported, because they lack a proper implementation of the IndexedDB API. You can use CBL-JS in those environments with the help of the fake-indexeddb package, but it's not very useful because databases are not persisted to disk.

This ReadMe last updated Nov 12 2025.

1. Getting Started / Documentation

The wiki has some documents introducing the API, and describing differences from other Couchbase Lite platforms.

For an example of using the API in a web page, see examples/browser.ts. If you want to run that example yourself, see "Kicking The Tires".

Using It In Your Own Projects

Install the NPM package "@couchbase/lite-js".

Install analytics (Reo.dev)

This package depends on reo-census, which sends a one-time install event to Reo.dev from its postinstall script. The event includes the package name and version, OS and Node.js details, the install timestamp and directory, your git user name, the domain of your git email address (not the full address), and CI environment info. Nothing is sent at runtime; CBL-JS itself makes no analytics calls.

To opt out, set PACKAGE_TRACKER_ANALYTICS=false when installing:

PACKAGE_TRACKER_ANALYTICS=false npm install @couchbase/lite-js

Installs that don't run dependency install scripts send nothing: npm install --ignore-scripts, Bun, pnpm 10+ and Yarn 4 (the last three skip dependency postinstall scripts by default).

2. Source Code

Code is in the src directory. The public API is declared in src/couchbase-lite.ts, which just re-exports public symbols.

Subdirectories are:

• blip: The BLIP RPC protocol, used by the replicator
• blob: Blob/attachment classes and support code
• database: Database, Collection and document implementation; plus the public Replicator class
• query: Query implementation
• replicator: Replicator implementation (but not its public API)
• util: Internal utilities

Tests are intermingled in the source directories, in files named *.test.ts.

3. Building It Yourself

Dependencies

For development you'll need to install either Bun, or node.js and npm. These directions assume bun; if you use node+npm, substitute npm for bun in command lines.

Package dependencies (will be installed by Bun):

• General:
  • @logtape/logtape -- Logging
• BLIP RPC:
  • @foxglove/crc -- CRC32 checksums.
  • pako -- data compression (it's a port of zlib.)
  • isomorphic-ws -- WebSockets (not needed in browsers.)
• Database:
  • dexie -- High-level wrapper for IndexedDB.
  • fake-indexeddb -- In-memory IndexedDB implementation (not needed in browsers)
  • sha.js -- SHA-1 digests (used instead of JS crypto because it's synchronous.)
  • buffer -- Required to use sha.js in a browser.
• Query:
  • ohm-js -- Parser library, used for N1QL/SQL++.
  • date-fns -- For the N1QL date/time functions
  • regexp.escape -- Escapes regular expression strings. Used in implementation of LIKE.

Building

To compile the TypeScript code in ./src into minified JavaScript files in ./dist:

1. bun install (first time only)
2. bun run build

Running Tests

Tests are in files named *.test.ts. They are run by vitest.

• To run the base (non-replicator) tests: bun run test
• To run the base tests in a browser: bun run test:browser
• To run the base tests with database encryption: bun run test:encrypted
• To run the replicator tests: bun run test:replicator or bun run test:replicator-encrypted (requires configuring Sync Gateway first; see notes in src/database/replicator.test.ts)
• To run the N1QL conformance tests: bun run test:n1ql or bun run test:niql-encrypted (requires downloading about 24MB of test data first; see directions in src/query/N1QLTestSuite.test.ts)

Integration Tests aka the TDK

Note: The TDK is internal to Couchbase, not public.

Integration & system tests of all Couchbase Lite platforms are performed by the Test Development Kit (TDK). The glue code that integrates CBL-JS is in the servers/javascript directory.

4. Running The Examples

…in a web browser

See the wiki page "Kicking the Tires".

…from the command line

We have a test of replication in a server environment (Bun or node.js). Since IndexedDB is not available, it uses the "fake-indexeddb" package; this database is ephemeral, since it's only for testing purposes.

To run, first read the instructions at the top of examples/sync_collections_node.ts and set up your server (Sync Gateway or Edge Server).

Then run bun run examples/sync_collections_node.ts