Keyv

Browser, Node, and Bun Support

Runtime support for Node.js, Bun, and browsers. Engines, Web Crypto, and what to install where.

Table of Contents

Node.js

The published engines field is Node.js 22.19+ (the current maintenance LTS line and newer). Official adapters follow the same floor. That is a versioning contract: we do not raise the Node floor on an already-released major.

npm install keyv

Core Keyv has one runtime dependency: hookified. The JSON serializer uses Buffer when present and btoa / atob otherwise.

Use @keyv/encrypt-node for crypto ciphers in Node.

Bun

We test Keyv on Bun. The default target is still Node.js. If something breaks on Bun, open an issue.

SQLite's optional bun:sqlite driver is the fastest in the SQLite benchmarks when you are already on Bun.

Browsers

Keyv's core source does not import Node built-ins. The in-memory store, serializer, hooks, stats, sanitization, and Web Crypto encryption work in browsers (and Cloudflare Workers / Deno) after your bundler includes the package.

import Keyv from "keyv";

const keyv = new Keyv({ store: new Map() });
await keyv.set("foo", "bar");

Use @keyv/encrypt-web for crypto.subtle. Use @keyv/cloudflare-kv inside Workers (bind mode) or from Node via the REST API.

Browser storage (localStorage, IndexedDB) is available through community adapters such as keyv-browser.

NOTE

Most official database adapters (Redis, Postgres, Mongo, …) expect a Node-like runtime and native clients. In the browser, stick to Map / LRU, BigMap, or a browser/Worker-safe adapter.

Serialization in the browser

KeyvJsonSerializer round-trips Uint8Array via base64 without Buffer. SuperJSON and msgpackr work wherever their own packages run.

Tests

  • Node: pnpm test in the monorepo
  • Bun: .github/workflows/bun-test.yaml
  • Browser: static "no Node builtin imports" checks plus happy-dom runtime tests in core/keyv
Edit this page