Tutorial
5 min read

Vercel KV Quickstart

Start using durable Redis with Vercel KV.
Table of Contents

Vercel KV is available on Hobby and Pro plans

In this quickstart, you'll learn how to do the following:

  • Create a KV store called my-store that is connected to one of your projects
  • See how to use the Vercel dashboard to create and manage your database
  • Populate the KV store using the CLI
  • Query the KV store using the SDK

Learn more about how Vercel KV works.

Vercel KV works with any frontend framework or as a standalone Redis database. First, install the package:

pnpm
yarn
npm
pnpm i @vercel/kv

Then, install the Vercel CLI so we can retrieve the Environment Variables:

pnpm
yarn
npm
pnpm i -g vercel@latest

Navigate to the Project you'd like to add a KV database to. Select the Storage tab, then select the Connect Database button.

Under the Create New tab, select KV and then the Continue button.

To use Vercel KV, you must accept the terms and conditions notice.

Next, create a new store in the dialog:

  1. Enter my-store (or any other name) under Database Name. The name can not exceed 32 characters
  2. Select a primary region
  3. Click Create & Continue
  4. Select which environments of the project to make the database available to. This determines the scope of the environment variables
  5. Click Connect

Your empty store is created in the primary region specified. This is the region that all write operations will be routed to.

Environment Variables for your KV store were automatically added to your project. These are used to connect to your store. Later in this quickstart, we'll pull them locally so you can use them with your project.

  • KV_URL
  • KV_REST_API_URL
  • KV_REST_API_TOKEN
  • KV_REST_API_READ_ONLY_TOKEN

You can send Redis commands to your KV store with the CLI interface in the dashboard. To access the CLI, select your KV store and go to the CLI tab.

Use the following command to create a user:me hash:

CLI
hset user:me email email@me.com id 123

You can then read the hash with the following command:

CLI
hgetall user:me

The CLI will respond with email, email@me.com, id, 123.

The CLI supports most Redis commands. See our compatibility docs to learn which commands are available.

When you created your KV database, your KV_REST_API_URL and KV_REST_API_TOKEN were created as Environment Variables automatically.

To use these Environment Variables in your code, we recommend pulling them with the following Vercel CLI command:

terminal
vercel env pull .env.development.local

You can now retrieve data from your KV Store. The Vercel KV client automatically handles serialization and deserialization of JSON data, so you can easily store JSON objects as well as plain strings.

Next.js (/app)
Next.js (/pages)
Other frameworks
app/api/user/route.ts
import { kv } from '@vercel/kv';
import { NextResponse } from 'next/server';
 
export async function GET() {
  const user = await kv.hgetall('user:me');
  return NextResponse.json(user);
}

To connect to multiple KV stores, use createClient:

Next.js (/app)
Next.js (/pages)
Other frameworks
app/api/user/route.ts
import { createClient } from '@vercel/kv';
import { NextResponse } from 'next/server';
 
export async function GET() {
  const users = createClient({
    url: process.env.USERS_REST_API_URL,
    token: process.env.USERS_REST_API_TOKEN,
  });
 
  const user = await users.hgetall('user:me');
 
  const products = createClient({
    url: process.env.PRODUCTS_REST_API_URL,
    token: process.env.PRODUCTS_REST_API_TOKEN,
  });
 
  const product = await products.hgetall('product:shirt');
 
  return NextResponse.json({ user, product });
}

See our Redis compatibility docs to learn more about available commands.

Run your application locally and visit /api/user to see your data.

Last updated on March 29, 2024