Couchbase Lite for JavaScript

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

It's intended for use in web browsers, or in JavaScript-based app frameworks like React Native.

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 Oct 29 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 package "@couchbase/lite-js".

Until the public release, this isn't in a public package registry, so you'll need to do a bit more:

1. Start Couchbase's GlobalProtect VPN
2. Run bun install @couchbase/lite-js --registry https://proget.sc.couchbase.com/npm/cbl-npm/ (or npm install if you swing that way.)

You'll need to use that same --registry flag when updating the package, too.

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
• query: Query implementation
• replicator: Replicator implementation (but not its public API)
• util: Internal utilities

Integration Tests aka the TDK

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.

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

You can run the tests in a Bun or node.js environment with either bun test or bun run test. The former uses Bun's built-in test runner, the latter uses vitest.

To run the tests in real browsers, run bun run test:browser.

By default, the tests in src/query/N1QLTestSuite.test.ts will be skipped because they require about 24MB of test data from the Server N1QL test suite repo. To enable those tests in Bun/node, follow the directions in the file. (These tests cannot be run in a browser because they access the filesystem.)

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