Getting started

Create a new project named kv-tutorial by running:

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.

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.

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

cd kv-tutorial

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

dash.cloudflare.com↗

Select Create application.

Select Start with Hello World! > Get started.

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

Select Deploy.

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

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

dash.cloudflare.com↗

Select Create instance.

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

Select Create.

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.

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

dash.cloudflare.com↗

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

Got to the Bindings tab, then select Add binding.

Select KV namespace > Add binding.

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.

Select Add binding to deploy your binding.

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

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

dash.cloudflare.com↗

Select the KV namespace you created (kv_tutorial_namespace).

Go to the KV Pairs tab.

Enter a <KEY> of your choice.

Enter a <VALUE> of your choice.

Select Add entry.

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

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.

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:

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

dash.cloudflare.com↗

Go to the KV namespace you created (kv_tutorial_namespace).

Go to the KV Pairs tab.

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
}

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");

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");

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

dash.cloudflare.com↗

Go to the kv-tutorial Worker you created.

Select Edit Code.

Clear the contents of the workers.js file, then paste the following code.

export default {
	async fetch(request, env, ctx) {
		try {
			await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
			const value = await env.USERS_NOTIFICATION_CONFIG.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" },
			});
		}
	},
};

export interface Env {
  USERS_NOTIFICATION_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
      const value = await env.USERS_NOTIFICATION_CONFIG.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" },
      });
    }
  },
} satisfies ExportedHandler<Env>;

The code above:

1. Writes a key to BINDING_NAME using KV's put() method.
2. Reads the same key using KV's get() method, and returns an error if the key is null (or in case the key is not set, or does not exist).
3. 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.

The browser should simply return the VALUE corresponding to the KEY you have specified with the get() method.

Select the dropdown arrow next to Deploy and select Save.

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

npm run deploy

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.

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

dash.cloudflare.com↗

Select your kv-tutorial Worker.

Select Deployments.

From the Version History table, select Deploy version.

From the Deploy version page, select Deploy.

This deploys the latest version of the Worker code to production.