Use Deno KV in Node with the new official npm package

4 min readDec 12, 2023

(Originally published on deno.com/blog.)

Since we’ve launched Deno KV, our globally-managed serverless database built right into the Deno runtime, developers love how simple it is to add state to their applications without configuration or provisioning a database:

const kv = await Deno.openKv();

Add state with Deno KV in a single line of code.

In addition to the ability to connect remotely to a managed Deno KV instance, we’ve also published a standalone open source denokv binary for self-hosting - including continuous backup to S3 or GCS with point-in-time recovery.

Today, we’re excited to bring Deno KV access to Node.js with our official Deno KV npm package. Now you can use Deno KV’s simple API to add a globally-distributed, ACID-supported database to your Node projects.

In this post, we’ll cover:

Installation and usage

To install the package:

npm install @deno/kv

Once you’ve added the package to your Node project, you can import the openKv function (supports both ESM import and CJS require-based usage):

import { openKv } from "@deno/kv";
const kv = await openKv(<KV Connect URL>);
// use the Deno KV api: https://deno.land/api?s=Deno.Kv&unstable 
const key = [ "users", crypto.randomUUID() ];
const value = { name: "Alice" };
await kv.set(key, value);
const result = await kv.get(key);
console.log(result.value); // { name: "Alice" }

By default, the access token used for authentication comes from the DENO_KV_ACCESS_TOKEN environment variable. You can also pass it explicitly via options:

import { openKv } from "@deno/kv";
const kv = await openKv(<KV Connect URL>, { accessToken: myToken });

KV Connect URLs to Deno Deploy KV databases look like:

https://api.deno.com/databases/<database-id>/connect

The database-id for your project can be found in the Deno Deploy dashboard, under the project’s KV tab.

Opening a KV instanc

The Deno KV npm package allows you to connect to four kinds of databases using a single function:

a globally-managed Deno Deploy KV instance, powered by FoundationDB and optimized for read and write latencies

const kv = await openKv(
  "https://api.deno.com/databases/<database-id>/connect",
);

a denokv service hosted on your own infrastructure, powered by SQLite

const kv = await openKv("http://localhost:4512");
// see https://github.com/denoland/denokv

a local database powered by SQLite

const kv = await openKv("kv.db");

or an in-memory KV database for testing

const kv = await openKv();

API

No matter which kind of database you choose, the returned kv instance has the same methods for database operations — following the KV API provided in Deno itself.

The get, getMany, set, delete, atomic, enqueue, and close methods are supported, even the new watch method!

The listenQueue method is supported for in-memory and SQLite databases, but not for remote databases (it’s not yet supported by the underlying protocol).

Check out an annotated example of how to interact with the KV API.

Provisioning a KV database on Deno Deploy

Deno KV on Deno Deploy is a globally-distributed, highly-performant database (built on FoundationDB) that scales without any provisioning or orchestration.

If you don’t have an existing Deno Deploy project, you can create a new Deno KV database for free without needing to deploy a project:

From your project page, create a new playground
Click on the settings icon, then “Project Settings”
Select the KV tab to copy out the database ID needed to construct the associated KV Connect URL to pass to openKv (see above)

Currently this process requires creating an empty project, we’re working to further simplify this flow in the future.

To remotely connect to your new Deno KV database, you’ll also need to create an access token and set that as the DENO_KV_ACCESS_TOKEN environment variable:

Go to your account settings
Scroll down to your Access Tokens and click “New Access Token”
Enter a description, like “Deno KV Access Token”
Copy the newly-generated access token

Finally, set your new token as the environment variable DENO_KV_ACCESS_TOKEN when running your Node project. Now you can connect remotely to a globally-managed Deno KV instance!

Supported runtimes

@deno/kv is targeted to Node 18+, optimized for performance and compatibility with databases created by Deno itself. It has no third-party npm package dependencies, and uses a single platform-specific binary for SQLite access on the four native architectures supported by Deno itself. The architecture-appropriate native dependency is selected and installed at npm install time using the standard peer dependency mechanism.

Deno KV uses V8’s serialization format for storing values in local and remote databases, available by default in Deno, and by default in Node via the built-in v8 module. This package will run on other Node-compatible runtimes, provided a compatible V8 serializer is available. See Other runtimes for more details.

Open source credits

The source code for this package is freely available, and utilizes:

protobuf code generated with pb
npm package generation with dnt
platform-specific binaries supporting the standard Node Node-API native interface, leveraging our existing denokv Rust codebase via the excellent NAPI-RS framework
an initial codebase contributed by John Spurlock, adapted from his open source kv-connect-kit project

What’s next

The release of the @deno/kv npm package means that you can now access Deno KV in your Node projects, whether that is the globally-managed Deno KV built on FoundationDB or a local one backed by SQLite. Building with Deno KV’s simple API makes it easy to add state to your projects. With Deno KV, along with other cloud primitives built into the Deno runtime such as Deno Queues and Deno Cron, creating a scalable, production-ready application is simpler than ever.

We just announced Deno Cron 🦕️🕒️, a zero config approach to adding and managing scheduled tasks, available in 1.38 or later and on Deno Deploy.