Getting started (10)

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 Oct 12, 2026 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 ↗︎.

<details>

<summary>

Node.js version manager

</summary>

Use <a href="https://viteplus.dev/guide/env">Vite+ (<code>vp env</code>) ↗︎</a> to install and manage Node.js versions.

For supported Node.js versions, refer to the <a href="https://developers.cloudflare.com/workers/wrangler/install-and-update/#install-wrangler">Wrangler system requirements</a>.

</details>

1. Create a Worker project

New to Workers?

Refer to How Workers works to learn about the Workers serverless execution model works. Go to the Workers Get started guide to set up your first Worker.

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

  1. Create a new project named kv-tutorial by running:npmyarnpnpm
   npm create cloudflare@latest -- kv-tutorial
   ```

yarn create cloudflare kv-tutorial ```

   pnpm 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 add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?*, 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](https://developers.cloudflare.com/workers/get-started/guide/#3-write-code) in `index.ts`.
   - A [`wrangler.jsonc`](https://developers.cloudflare.com/workers/wrangler/configuration/) 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:

```sh
   cd kv-tutorial
   ```

Note

If you are familiar with Cloudflare Workers, or initializing projects in a Continuous Integration (CI) environment, initialize a new project non-interactively by setting `CI=true` as an [environmental variable](https://developers.cloudflare.com/workers/configuration/environment-variables/) when running `create cloudflare@latest`.

For example: `CI=true npm create cloudflare@latest kv-tutorial --type=simple --git --ts --deploy=false` creates a basic "Hello World" project ready to build on.

1. In the Cloudflare dashboard, go to the **Workers & Pages** page. [Go to **Workers & Pages** ↗](https://dash.cloudflare.com/?to=/:account/workers-and-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](https://developers.cloudflare.com/kv/concepts/kv-namespaces/) is a key-value database replicated to Cloudflare's global network.

You can use [Wrangler](https://developers.cloudflare.com/workers/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.

Note

KV operations are scoped to your account.

To create a KV namespace via Wrangler:

1. Open your terminal and run the following command:

```sh
   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`.

```sh
   npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG
   ```

```sh
   🌀 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** ↗](https://dash.cloudflare.com/?to=/:account/workers/kv/namespaces)
2. Select **Create instance**.
3. Enter a name for your namespace. For this tutorial, use `kv_tutorial_namespace`.
4. Select **Create**.

### KV Instant namespaces

Note

Workers KV Instant is currently in private beta. To enroll, contact your Cloudflare account team or [sign up ↗︎](https://www.cloudflare.com/resource/workers-kv-instant-beta/) and tell us about your use case.

Use Workers KV Instant for small, read-heavy application configurations values that update infrequently and are proactively propagated across Cloudflare's network.

To optionally create a KV Instant namespace named `APP_CONFIG` with [Wrangler](https://developers.cloudflare.com/workers/wrangler/), pass `--experimental-mode instant`:

npmyarnpnpm

npx wrangler@latest kv namespace create APP_CONFIG --experimental-mode instant

yarn wrangler@latest kv namespace create APP_CONFIG --experimental-mode instant

pnpm wrangler@latest kv namespace create APP_CONFIG --experimental-mode instant


To create the namespace with [Cloudflare CLI](https://developers.cloudflare.com/cf/), pass `--namespaceMode instant`:

```sh
cf kv namespaces create --title APP_CONFIG --namespaceMode instant

Alternatively, create it through the API with mode: "instant":

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

  • <code>Workers KV Storage Write</code>

</details>

Create a namespacebash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces" \
    --request POST \
    --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    --json '{
        "title": "APP_CONFIG",
        "mode": "instant"
    }'

KV Instance namespaces have additional limitations compared to classic namespaces. Refer to KV Instant limits before choosing this mode.

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.

Bindings

A binding is how your Worker interacts with external resources such as KV namespaces. A binding is a runtime variable that the Workers runtime provides to your code. You can declare a variable name in your Wrangler file that binds to these resources at runtime, and interact with them through this variable. Every binding's variable name and behavior is determined by you when deploying the Worker.

Refer to Environment for more information.

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

```toml
   [[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 ↗︎](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). 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** ↗](https://dash.cloudflare.com/?to=/:account/workers-and-pages)
2. Select the `kv-tutorial` Worker you created in [step 1](https://developers.cloudflare.com/kv/get-started/#1-create-a-worker-project).
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](https://developers.cloudflare.com/kv/get-started/#2-create-a-kv-namespace) 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](https://developers.cloudflare.com/workers/wrangler/install-and-update/) or directly from your [Workers](https://developers.cloudflare.com/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.

```sh
   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](https://developers.cloudflare.com/kv/get-started/#2-create-a-kv-namespace).

```sh
   npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"
   ```

```sh
   Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.
   ```

Using \`--namespace-id\`

Instead of using `--binding`, you can also use `--namespace-id` to specify which KV namespace should receive the operation:

```sh
npx wrangler kv key put --namespace-id=<BINDING_ID> "<KEY>" "<VALUE>"