# 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][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 Nov 12 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`](./examples/browser.ts).
If you want to run that example yourself, see ["Kicking The Tires"][KICKING].

### Using It In Your Own Projects

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

## 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](https://bun.sh),
or [node.js](https://nodejs.org) and [npm](https://www.npmjs.com).
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`](https://www.npmjs.com/package/@logtape/logtape) -- Logging
* BLIP RPC:
  * [`@foxglove/crc`](https://www.npmjs.com/package/@foxglove/crc) -- CRC32 checksums.
  * [`pako`](https://www.npmjs.com/package/pako) -- data compression (it's a port of zlib.)
  * [`isomorphic-ws`](https://www.npmjs.com/package/isomorphic-ws) -- WebSockets (not needed in browsers.)
* Database:
  * [`dexie`](https://www.npmjs.com/package/dexie) -- High-level wrapper for IndexedDB.
  * [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb) -- In-memory IndexedDB implementation (not needed in browsers)
  * [`sha.js`](https://www.npmjs.com/package/sha.js) -- SHA-1 digests (used instead of JS crypto because it's synchronous.)
  * [`buffer`](https://www.npmjs.com/package/buffer) -- Required to use `sha.js` in a browser.
* Query:
  * [`ohm-js`](https://www.npmjs.com/package/ohm-js) -- Parser library, used for N1QL/SQL++.
  * [`date-fns`](https://www.npmjs.com/package/date-fns) -- For the N1QL date/time functions
  * [`regexp.escape`](https://www.npmjs.com/package/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] (TDK). The glue code that integrates CBL-JS is in the
[`servers/javascript`][TDK_JS] directory.

## 4. Running The Examples

### …in a web browser

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

### …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"][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`](./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