# @vercel/kv

> Durable Redis

Latest version **3.0.0** (published 2024-09-27) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @vercel/kv
pnpm add @vercel/kv
yarn add @vercel/kv
bun add @vercel/kv
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2024-09-27 |
| First published | 2023-03-31 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.6 |
| Dependencies | 1 |
| Unpacked size | 39.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 596 |
| Maintainers | snokohn, matt.straka, ijjk, quietshu, vercel-release-bot, nick.tracey, matheuss, chriswdmr, zeit-bot |

## Links

- npm: https://www.npmjs.com/package/@vercel/kv
- Repository: https://github.com/vercel/storage
- Homepage: https://vercel.com
- Issues: https://github.com/vercel/storage/issues
- npm.io page: https://npm.io/package/@vercel/kv

## Dependencies (1)

- [@upstash/redis](https://npm.io/package/@upstash/redis.md) ^1.34.0

## Recent versions

- 3.0.0 (latest) — 2024-09-27
- 2.0.0-c16c2db6-20240527144145 (snapshot) — 2024-05-27
- 0.1.2-canary.0 (canary) — 2023-05-03
- 0.1.0-bundling.3 (bundling) — 2023-04-30
- 2.0.0 — 2024-05-27
- 2.0.0-e14181a4-20240517133706 — 2024-05-17
- 1.1.0-34d6b1d9-20240516131712 — 2024-05-16
- 1.0.1 — 2023-12-08
- 1.0.0 — 2023-11-08
- 0.2.4 — 2023-10-31
- 0.2.3 — 2023-09-19
- 0.2.3-ec71772f-20230919094854 — 2023-09-19
- 0.2.3-66547161-20230919094556 — 2023-09-19
- 0.2.3-66547161-20230918125816 — 2023-09-18
- 0.2.2 — 2023-06-22
- … 9 more at https://npm.io/package/@vercel/kv/versions

## README

# @vercel/kv

A client that works with Vercel KV.

## Install

```sh
npm install @vercel/kv

```

## Usage

```js
import { kv } from '@vercel/kv';

// string
await kv.set('key', 'value');
let data = await kv.get('key');
console.log(data); // 'value'

await kv.set('key2', 'value2', { ex: 1 });

// sorted set
await kv.zadd(
  'scores',
  { score: 1, member: 'team1' },
  { score: 2, member: 'team2' },
);
data = await kv.zrange('scores', 0, 0);
console.log(data); // [ 'team1' ]

// list
await kv.lpush('elements', 'magnesium');
data = await kv.lrange('elements', 0, 100);
console.log(data); // [ 'magnesium' ]

// hash
await kv.hset('people', { name: 'joe' });
data = await kv.hget('people', 'name');
console.log(data); // 'joe'

// sets
await kv.sadd('animals', 'cat');
data = await kv.spop('animals', 1);
console.log(data); // [ 'cat' ]

// scan for keys
for await (const key of kv.scanIterator()) {
  console.log(key);
}
```

### Custom Environment Variables

By default `@vercel/kv` reads the `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables. Use the following function in case you need to define custom values

```js
import { createClient } from '@vercel/kv';

const kv = createClient({
  url: 'https://<hostname>.redis.vercel-storage.com',
  token: '<token>',
});

await kv.set('key', 'value');
```

### Automatic Deserialization

The default `kv` client automatically deserializes values returned from the database via `JSON.parse`. If this behaviour is undesired, create a custom KV client via the `createClient` method with `automaticDeserialization: false`. All data will be returned as strings.

```js
import { kv, createClient } from '@vercel/kv';

const customKvClient = createClient({
  url: process.env.KV_REST_API_URL,
  token: process.env.KV_REST_API_TOKEN,
  automaticDeserialization: false,
});

await customKvClient.set('object', { hello: 'world' });

console.log(await kv.get('object')); // { hello: 'world' }
console.log(await customKvClient.get('object')); // '{"hello":"world"}'
```

## Docs

See the [documentation](https://www.vercel.com/docs/storage/vercel-kv) for details.

## A note for Vite users

`@vercel/kv` reads database credentials from the environment variables on `process.env`. In general, `process.env` is automatically populated from your `.env` file during development, which is created when you run `vc env pull`. However, Vite does not expose the `.env` variables on `process.env.`

You can fix this in **one** of following two ways:

1. You can populate `process.env` yourself using something like `dotenv-expand`:

```shell
pnpm install --save-dev dotenv dotenv-expand
```

```js
// vite.config.js
import dotenvExpand from 'dotenv-expand';
import { loadEnv, defineConfig } from 'vite';

export default defineConfig(({ mode }) => {
  // This check is important!
  if (mode === 'development') {
    const env = loadEnv(mode, process.cwd(), '');
    dotenvExpand.expand({ parsed: env });
  }

  return {
    ...
  };
});
```

2. You can provide the credentials explicitly, instead of relying on a zero-config setup. For example, this is how you could create a client in SvelteKit, which makes private environment variables available via `$env/static/private`:

```diff
import { createClient } from '@vercel/kv';
+ import { KV_REST_API_URL, KV_REST_API_TOKEN } from '$env/static/private';

const kv = createClient({
-  url: 'https://<hostname>.redis.vercel-storage.com',
-  token: '<token>',
+  url: KV_REST_API_URL,
+  token: KV_REST_API_TOKEN,
});

await kv.set('key', 'value');
```

## FAQ

### Does the `@vercel/kv` package support [Redis Streams](https://redis.io/docs/data-types/streams/)?

No, the `@vercel/kv` package does not support Redis Streams. To use Redis Streams with Vercel KV, you must connect directly to the database server via packacges like [`io-redis`](https://github.com/redis/ioredis) or [`node-redis`](https://github.com/redis/node-redis).

```js
import { createClient } from 'redis';

const client = createClient({
  url: process.env.KV_URL,
});

await client.connect();
await client.xRead({ key: 'mystream', id: '0' }, { COUNT: 2 });
```

---
_Source: https://npm.io/package/@vercel/kv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._