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][INDEXEDDB] API.
You can use CBL-JS in those environments with the help of the [fake-indexeddb][FAKE] 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][WIKI] has some documents introducing the [API][APIDOCS], 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"][KICKING].

$3

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

$3

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

3. Building It Yourself

$3

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.

$3

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

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

$3

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

$3

See the wiki page ["Kicking the Tires"][KICKING].

$3

We have a test of replication in a server environment (Bun or node.js).
Since IndexedDB is not available, it uses the ["fake-indexeddb"][FAKE] 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

[WIKI]: https://github.com/couchbaselabs/couchbase-lite-js/wiki
[APIDOCS]: https://glowing-invention-kr285q7.pages.github.io/modules.html
[KICKING]: https://github.com/couchbaselabs/couchbase-lite-js/wiki/Kicking-The-Tires
[INDEXEDDB]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
[FAKE]: https://www.npmjs.com/package/fake-indexeddb
[TDK]: https://github.com/couchbaselabs/couchbase-lite-tests
[TDK_JS]: https://github.com/couchbaselabs/couchbase-lite-tests/tree/main/servers/javascript