Skip to content

Getting started

Create a basic key-value store which stores the notification configuration of all users in an application, where each user may have enabled or disabled notifications.

Last updated View as MarkdownAgent setup

Workers KV provides low-latency, high-throughput global storage to your Cloudflare Workers applications. Workers KV is ideal for storing user configuration data, routing data, A/B testing configurations and authentication tokens, and is well suited for read-heavy workloads.

This guide instructs you through:

  • Creating a KV namespace.
  • Writing key-value pairs to your KV namespace from a Cloudflare Worker.
  • Reading key-value pairs from a KV namespace.

You can perform these tasks through the Wrangler CLI or through the Cloudflare dashboard.

Quick start

If you want to skip the setup steps and get started quickly, click on the button below.

Deploy to Cloudflare

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers. Use this option if you are familiar with Cloudflare Workers, and wish to skip the step-by-step guidance.

You may wish to manually follow the steps if you are new to Cloudflare Workers.

Prerequisites

  1. Sign up for a Cloudflare account ↗.
  2. Install Node.js ↗.

Node.js version manager

Use a Node version manager like Volta ↗ or nvm ↗ to avoid permission issues and change Node.js versions. Wrangler, discussed later in this guide, requires a Node version of 16.17.0 or later.

1. Create a Worker project

Create a new Worker to read and write to your KV namespace.

  1. Create a new project named kv-tutorial by running:

    npm create cloudflare@latest -- kv-tutorial

    For setup, select the following options:

    • For What would you like to start with?, choose Hello World example.
    • For Which template would you like to use?, choose Worker only.
    • For Which language do you want to use?, choose TypeScript.
    • For Do you want to use git for version control?, choose Yes.
    • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

    This creates a new kv-tutorial directory, illustrated below.

    • kv-tutorial/
      • node_modules/
      • test/
      • src
        • index.ts
      • package-lock.json
      • package.json
      • testconfig.json
      • vitest.config.mts
      • worker-configuration.d.ts
      • wrangler.jsonc

    Your new kv-tutorial directory includes:

    • A "Hello World" Worker in index.ts.
    • A wrangler.jsonc configuration file. wrangler.jsonc is how your kv-tutorial Worker accesses your kv database.

  2. Change into the directory you just created for your Worker project:

    cd kv-tutorial

  1. In the Cloudflare dashboard, go to the Workers & Pages page.

    Go to Workers & Pages ↗

  2. Select Create application.

  3. Select Start with Hello World! > Get started.

  4. Name your Worker. For this tutorial, name your Worker kv-tutorial.

  5. Select Deploy.

2. Create a KV namespace

A KV namespace is a key-value database replicated to Cloudflare's global network.

You can use Wrangler to create a new KV namespace. You can also use it to perform operations such as put, list, get, and delete within your KV namespace.

To create a KV namespace via Wrangler:

  1. Open your terminal and run the following command:

    npx wrangler kv namespace create <BINDING_NAME>

    The npx wrangler kv namespace create <BINDING_NAME> subcommand takes a new binding name as its argument. A KV namespace is created using a concatenation of your Worker's name (from your Wrangler file) and the binding name you provide. A <BINDING_ID> is randomly generated for you.

    For this tutorial, use the binding name USERS_NOTIFICATION_CONFIG.

    npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG
    🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

  1. In the Cloudflare dashboard, go to the Workers KV page.

    Go to Workers KV ↗

  2. Select Create instance.

  3. Enter a name for your namespace. For this tutorial, use kv_tutorial_namespace.

  4. Select Create.

3. Bind your Worker to your KV namespace

You must create a binding to connect your Worker with your KV namespace. Bindings allow your Workers to access resources, like KV, on the Cloudflare developer platform.

To bind your KV namespace to your Worker:

  1. In your Wrangler file, add the following with the values generated in your terminal from step 2:

    {
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}
    [[kv_namespaces]]
binding = "USERS_NOTIFICATION_CONFIG"
id = "<BINDING_ID>"

    Binding names do not need to correspond to the namespace you created. Binding names are only a reference. Specifically:

    • The value (string) you set for binding is used to reference this KV namespace in your Worker. For this tutorial, this should be USERS_NOTIFICATION_CONFIG.
    • The binding must be a valid JavaScript variable name ↗. For example, binding = "MY_KV" or binding = "routingConfig" would both be valid names for the binding.
    • Your binding is available in your Worker at env.<BINDING_NAME> from within your Worker. For this tutorial, the binding is available at env.USERS_NOTIFICATION_CONFIG.

  1. In the Cloudflare dashboard, go to the Workers & Pages page.

    Go to Workers & Pages ↗

  2. Select the kv-tutorial Worker you created in step 1.

  3. Got to the Bindings tab, then select Add binding.

  4. Select KV namespace > Add binding.

  5. Name your binding (BINDING_NAME) in Variable name, then select the KV namespace (kv_tutorial_namespace) you created in step 2 from the dropdown menu.

  6. Select Add binding to deploy your binding.

4. Interact with your KV namespace

You can interact with your KV namespace via Wrangler or directly from your Workers application.

4.1. Write a value

To write a value to your empty KV namespace using Wrangler:

  1. Run the wrangler kv key put subcommand in your terminal, and input your key and value respectively. <KEY> and <VALUE> are values of your choice.

    npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"

    In this tutorial, you will add a key user_1 with value enabled to the KV namespace you created in step 2.

    npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"
    Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.