Node.js bindings for Couchbase Lite

I’m building a Node native addon wrapper around Couchbase Lite for C to provide a cross platform solution for Windows, MacOS, Linux, iOS, and Android.

The library currently supports nearly all the features in the Community Edition (including querying, replication, and blobs), but has only been tested on MacOS so far, and there are occasional bugs that have been extremely difficult to track down.

I’ve been writing JavaScript and a handful of other languages for 20 years, but this is my first time writing C and using Node-API. My lack of experience in these areas is holding me back from providing a first-rate library to the community. So I’m hoping to get some help on this project from others more experienced in C. I also welcome any feedback from other Node users interested in this project.

Note: this is very much a work in progress and the API is not guaranteed to be consistent.


Hi @jpsilva,

Thanks a lot for your effort in developing the Node.js bindings for Couchbase Lite. We would love to have you listed alongside some of the other bindings for Couchbase Lite. I can also suggest joining our Discord community where you could get some support from other community members/staff.

Additionally, it might be useful for you to get in touch with the developers of another one of our community bindings, the Dart/Flutter package.

1 Like

Thanks, @nithishr.

I took inspiration from the other listed bindings when building this library and would be happy to join their ranks. I see the Dart bindings authors created a GitHub org just for that library, and I think I’ll do the same so it doesn’t look like just some abandonware personal project.

Thanks for the invite to the Discord community and link to the Dart/Flutter bindings. I’ll reach out in both places for help and feedback.

Do you have any preference on an NPM package name for this? I’m not looking to step on Couchbase’s toes by stealing the “cblite” or “couchbase-lite” package name.

I’ve moved the repo to GitHub - recouch/couchbase-lite-js

This makes no sense we already got nodejs bindings Update binding.ts by frank-dspeed · Pull Request #9 · couchbaselabs/vscode-cblite · GitHub

some more background read the readme of the vscode extension there is a section how to build the nodejs bindings but thanks for your alternativ implementation

Well that would certainly have saved me some time. I never wanted to implement my own solution; just couldn’t find a solution anywhere else.

Unfortunately, this doesn’t seem to cover all the bases. It lacks support for replication and (if I’m not mistaken) saving blobs. That makes sense for a vscode plugin, but I believe it would be needed for most applications since replication is the reason you would choose Couchbase Lite. Are there plans to add replication?

Also unfortunately, I can’t get the plugin to work for me in vscode to try it out. After installing, the “Open database” command doesn’t appear to do anything. Nothing in the output panel to debug it either.

The C++ code in vscode-cblite is certainly easier to read. I chose to go with plain C because the Couchbase Lite C readme states that other language bindings “(even C++) have no official support by Couchbase.” I thought it would be best to minimize the number of layers of abstraction, especially if those layers don’t have official support. Though I could be convinced otherwise.

I did not know that the Node.js bindings were part of the VS Code extension repo. Currently, the bindings provided as part of the plugin are also not officially supported.

The support for Node.js bindings for CB Lite might be something @priya.rajagopal / @borrrden could comment on.

Just as a technical FYI, the reason C++ was used was because the framework for binding required it (probably because it is easier to translate to a language like Javascript that uses classes). And also note that unlike the other bindings, we will respond more quickly to anything reported about C++. Since the C++ bindings are header only, the ultimate plan is to support and distribute them.

As far as official node.js support I cannot say anything about that. Casually adding in new supported platforms that cover multiple operating systems puts a very large resource strain on any development and QE team.

I can only say for me the bindings did work as also the vscode extension and i am vscode contributor always on newst edge versions of everything to address issues even most time before they reach LTS and the c++ assumption is correct from @borrrden while the most best would even be rust and go for neon bindings as this skips the ugly gyp and allows better cross platform builds faster.

also reduces maintainance overhead

Should Rust be compiled into a native node addon or into WASM? The latter might be even easier and more portable, but I don’t know the pros and cons of each approach.

The Rust bindings listed on couchbase-lite-C are incomplete and unmaintained. If that got back on track, I would love to use it.

It is unlikely that the Rust bindings will get back on track from our side. We don’t have anyone who knows Rust particularly well, and since I looked at Rust years ago it has transformed into something unrecognizable to me. Not to mention it then goes through two layers of unsupported, unofficial projects instead of one (node.js → rust). I guess you could make the same argument now (node.js → c++) but at least we have developers who are well versed in C++ working on the latter variant.

To clarify what I mean by “unsupported” and “unofficial”, the definition of unsupported and unofficial for our company are basically the same thing: No paid support is provided for it and you basically use it at your own risk (as most open source licenses state). It also gets lower priority than official supported products. From the outside, the rough rule is that things in couchbase org are supported and things in couchbaselabs org are not but that is not the absolute. I expect that the node.js bindings work. I tested them as such, but mostly out of curiosity (I never was a personal fan of node.js or Javascript in general). They are also, notably, far from a complete covering of the API. They cover only such items as the vscode plugin requires. The vscode plugin is also unsupported in the same sense.

Also, the biggest purpose of the bindings repos that we have on top of C is just to show PoC that it is possible to leverage C to bring Couchbase Lite to other languages, not to claim that we are going to release the next platform as language X. I’m not sure if this demonstration was a factor or not, but as noted above a community user created a beautiful set of Dart bindings for use in Flutter, for example.

In terms of package naming, I’m not familiar with NPM specifically but most package managers offer the concept of prefixes. Were we ever to make an entry into NPM I imagine we would claim the couchbase. prefix as we have done elsewhere (and get a blue checkmark for it, if that is a thing, thereby invalidating other packages that may have that prefix). So if your package does not contain that prefix it should be fine, even if it contains the words couchbase lite inside of it. This is from a technical standpoint though, and I don’t know what other stances need to be considered ( @priya.rajagopal ? )

Yes, NPM has prefixes that begin with @ and end in a slash. E.g., “@couchbase/cblite”. I definitely won’t be taking that.

Ok i got clarity


  • You cannot bundle/distribute the CE/EE binary version with the bindings. The CBL libraries should be specified as dependencies and pulled down separately by the users. That way, the users are agreeing to T&C of EE/CE license respectively and also compliant with commercial use of BSL license
  • You cannot link to any BSL licensed code (i.e. build CBL dependency and link the library).


We should not ship any bindings we can only share build instructions including download instructions.
as couchbase says download and executing build instructions manual is equal to license aggreement.

we can ship d.ts files for the resulting bindings.

also it makes no sense to build bindings for the community edition of CB-Lite as even that is covered by the BSL so it makes total no diffrence from User perspectiv if he uses CB-lite ee or ce. Both are useable without a EE Subscription out of License view. There is no single case where the Community Edition could be used and the EE Could not.

Hmm, that makes things a bit more difficult for users. My library currently downloads the Couchbase Lite code and builds upon install. Since the couchbase-lite-C repo doesn’t give any rules about how to include the source code (it uses the Apache 2.0 license), I assumed the same would follow about the built dynamic libraries. Maybe we can build directly from the source code. Can you share where you found those licensing guidelines?

It makes sense to build bindings for the Community Edition though, since that is free to use in production, whereas the Enterprise Edition requires a paid subscription for use in production.