Skip to content
Cloudflare Docs

Getting started

Last reviewed: 9 days ago

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.

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:

    Terminal window
    npm create cloudflare@latest -- kv-tutorial

    For setup, select the following options:

    • For What would you like to start with?, choose Hello World Starter.
    • 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.

    • Directorykv-tutorial/
      • Directorynode_modules/
        • …
      • Directorytest/
        • …
      • Directorysrc
        • 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:

    Terminal window
    cd kv-tutorial

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:

    Terminal window
    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.

    Terminal window
    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>"
        }
      ]
    }

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>"
        }
      ]
    }

    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.

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.

    Terminal window
    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.

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

4.2. Get a value

To access the value from your KV namespace using Wrangler:

  1. Run the wrangler kv key get subcommand in your terminal, and input your key value:

    Terminal window
    npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"

    In this tutorial, you will get the value of the key user_1 from the KV namespace you created in step 2.

    Terminal window
    npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text

    Similar to the put command, the get command can also be used to access a KV namespace in two ways - with --binding or --namespace-id:

Refer to the kv bulk documentation to write a file of multiple key-value pairs to a given KV namespace.

5. Access your KV namespace from your Worker

  1. In your Worker script, add your KV binding in the Env interface. If you have bootstrapped your project with JavaScript, this step is not required.

    interface Env {
      USERS_NOTIFICATION_CONFIG: KVNamespace;
      // ... other binding types
    }

  2. Use the put() method on USERS_NOTIFICATION_CONFIG to create a new key-value pair. You will add a new key user_2 with value disabled to your KV namespace.

    let value = await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");

  3. Use the KV get() method to fetch the data you stored in your KV namespace. You will fetch the value of the key user_2 from your KV namespace.

    let value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");

Your Worker code should look like this:

export default {
  async fetch(request, env, ctx) {
    try {
      await env.USER_NOTIFICATION.put("user_2", "disabled");
      const value = await env.USER_NOTIFICATION.get("user_2");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      console.error(`KV returned error:`, err);
      const errorMessage =
        err instanceof Error
          ? err.message
          : "An unknown error occurred when accessing KV storage";
      return new Response(errorMessage, {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    }
  },
};

The code above:

  1. Writes a key to your KV namespace using KV's put() method.
  2. Reads the same key using KV's get() method.
  3. Checks if the key is null, and returns a 404 response if it is.
  4. If the key is not null, it returns the value of the key.
  5. Uses JavaScript's try...catch ↗ exception handling to catch potential errors. When writing or reading from any service, such as Workers KV or external APIs using fetch(), you should expect to handle exceptions explicitly.

6. Deploy your Worker

Deploy your Worker to Cloudflare's global network.

  1. Run the following command to deploy KV to Cloudflare's global network:

    Terminal window
    npm run deploy

  2. Visit the URL for your newly created Workers KV application.

    For example, if the URL of your new Worker is kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev, accessing https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ sends a request to your Worker that writes (and reads) from Workers KV.

Summary

By finishing this tutorial, you have:

  1. Created a KV namespace
  2. Created a Worker that writes and reads from that namespace
  3. Deployed your project globally.

Next steps

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the Cloudflare Developers community on Discord ↗.