Improving KV getting started guide

Oxyjun · Oxyjun · commit cecf71155f44 · 2025-05-20T13:53:35.000+01:00
diff --git a/src/content/docs/kv/get-started.mdx b/src/content/docs/kv/get-started.mdx
@@ -1,11 +1,14 @@
 ---
 title: Getting started
 pcx_content_type: get-started
+summary: |
+    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.
+updated: 2025-05-19
 sidebar:
   order: 2
 ---
 
-import { Render, PackageManagers, Steps, FileTree, Details, Tabs, TabItem, WranglerConfig } from "~/components";
+import { Render, PackageManagers, Steps, FileTree, Details, Tabs, TabItem, WranglerConfig, GitHubCode } from "~/components";
 
 Workers KV provides low-latency, high-throughput global storage to your [Cloudflare Workers](/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.
 
@@ -15,7 +18,17 @@ This guide instructs you through:
 - 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 CLI or through the Cloudflare dashboard.
+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](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/update/kv/kv/kv-get-started)
+
+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
 
@@ -99,7 +112,7 @@ Create a new Worker to read and write to your KV namespace.
 
 ## 2. Create a KV namespace
 
-A [KV namespace](/kv/concepts/kv-namespaces/) is a key-value database replicated to Cloudflare’s global network.
+A [KV namespace](/kv/concepts/kv-namespaces/) is a key-value database replicated to Cloudflare's global network.
 
 <Tabs syncKey = 'CLIvsDash'> <TabItem label='CLI'>
 
@@ -119,21 +132,26 @@ To create a KV namespace via Wrangler:
 	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.
+	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 `BINDING_NAME`.
+	For this tutorial, use the binding name `USERS_NOTIFICATION_CONFIG`.
 
-	```sh
-	npx wrangler kv namespace create BINDING_NAME
+	```sh ins="USERS_NOTIFICATION_CONFIG"
+	npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG
 	```
 
 	```sh output
-	🌀  Creating namespace with title kv-tutorial-BINDING_NAME
-	✨  Success!
-	Add the following to your configuration file:
-	[[kv_namespaces]]
-	binding = "BINDING_NAME"
-	id = "<BINDING_ID>"
+	🌀 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>"
+			}
+		]
+	}
 	```
 
 </Steps>
@@ -163,17 +181,17 @@ To bind your KV namespace to your Worker:
 
 	```toml
 	[[kv_namespaces]]
-	binding = "<BINDING_NAME>"
+	binding = "USERS_NOTIFICATION_CONFIG"
 	id = "<BINDING_ID>"
 	```
 
 	</WranglerConfig>
 
    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_NAME>` is used to reference this KV namespace in your Worker. For this tutorial, this should be `BINDING_NAME`.
+	- 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.
+	- 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`.
 </Steps>
 
 :::note[Bindings]
@@ -201,7 +219,7 @@ Refer to [Environment](/kv/reference/environments/) for more information.
 
 You can interact with your KV namespace via [Wrangler](/workers/wrangler/install-and-update/) or directly from your [Workers](/workers/) application.
 
-### Write a value
+### 4.1. Write a value
 
 <Tabs syncKey='CLIvsDash'><TabItem label = 'CLI'>
 
@@ -214,24 +232,29 @@ To write a value to your empty KV namespace using Wrangler:
 	npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"
 	```
 
+	```sh
+	npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"
+	```
 	```sh output
-	Writing the value "<VALUE>" to key "<KEY>" on namespace <BINDING_ID>.
+	Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.
 	```
 </Steps>
 
+:::note
 Instead of using `--binding`, you can also use `--namespace-id` to specify which KV namespace should receive the operation:
 
-```sh
+```sh "--namespace-id=<BINDING_ID>"
 npx wrangler kv key put --namespace-id=<BINDING_ID> "<KEY>" "<VALUE>"
 ```
 
 ```sh output
 Writing the value "<VALUE>" to key "<KEY>" on namespace <BINDING_ID>.
 ```
+:::
 
 To create a key and a value in local mode, add the `--local` flag at the end of the command:
 
-```sh
+```sh ins="--local"
 npx wrangler kv key put --namespace-id=xxxxxxxxxxxxxxxx "<KEY>" "<VALUE>" --local
 ```
 
@@ -247,7 +270,7 @@ npx wrangler kv key put --namespace-id=xxxxxxxxxxxxxxxx "<KEY>" "<VALUE>" --loca
 
 </TabItem> </Tabs>
 
-### Get a value
+### 4.2. Get a value
 
 <Tabs syncKey='CLIvsDash'><TabItem label = 'CLI'>
 
@@ -261,7 +284,7 @@ To access the value using Wrangler:
     npx wrangler kv key get [OPTIONS] "<KEY>"
     ```
 
-    A KV namespace can be specified in two ways:
+    A KV namespace can be specified in two ways. Replace `[OPTIONS]` with `--binding` or `--namespace-id`:
 
     <Details header="With a `--binding`">
 
@@ -278,9 +301,15 @@ To access the value using Wrangler:
     ```
     </Details>
 
+		For example, using the `--binding` option:
+
+		```sh
+		npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1"
+		```
+
 </Steps>
 
-You can add a `--preview` flag to interact with a preview namespace instead of a production namespace.
+{/* You can add a `--preview` flag to interact with a preview namespace instead of a production namespace. */}
 
 :::caution
 
@@ -320,66 +349,41 @@ To have `wrangler dev` connect to your Workers KV namespace running on Cloudflar
 
 	```ts
 	interface Env {
-		BINDING_NAME: KVNamespace;
+		USERS_NOTIFICATION_CONFIG: KVNamespace;
 		// ... other binding types
 	}
 	```
 
-2. Use the `put()` method on `BINDING_NAME` to create a new key-value pair, or to update the value for a particular key:
+2. Use the `put()` method on `USERS_NOTIFICATION_CONFIG` to create a new key-value pair:
 
 	```ts
-	let value = await env.BINDING_NAME.put(key, value);
+	let value = await env.USERS_NOTIFICATION_CONFIG.put(key, value);
 	```
 
 3. Use the KV `get()` method to fetch the data you stored in your KV database:
 
 	```ts
-	let value = await env.BINDING_NAME.get("KEY");
+	let value = await env.USERS_NOTIFICATION_CONFIG.get("KEY");
 	```
 </Steps>
 
 Your Worker code should look like this:
 
-```ts
-export interface Env {
-	BINDING_NAME: KVNamespace;
-}
-
-export default {
-	async fetch(request, env, ctx): Promise<Response> {
-		try {
-			await env.BINDING_NAME.put("KEY", "VALUE");
-			const value = await env.BINDING_NAME.get("KEY");
-			if (value === null) {
-				return new Response("Value not found", { status: 404 });
-			}
-			return new Response(value);
-		} catch (err) {
-			// In a production application, you could instead choose to retry your KV
-			// read or fall back to a default code path.
-			console.error(`KV returned error: ${err}`);
-			return new Response(err, { status: 500 });
-		}
-	},
-} satisfies ExportedHandler<Env>;
-```
+<GitHubCode
+    repo="cloudflare/docs-examples"
+    file="kv/kv-get-started/src/index.ts"
+    commit="831724c421748229864c1ea28c854e352c62625e"
+    lang="ts"
+		lines="1-26"
+    useTypeScriptExample={true}
+/>
 
 The code above:
 
-1. Writes a key to `BINDING_NAME` using KV's `put()` method.
+1. Writes a key to `USERS_NOTIFICATION_CONFIG` binding 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/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.
 
-To run your project locally, enter the following command within your project directory:
-
-```sh
-npx wrangler dev
-```
-
-When you run `wrangler dev`, Wrangler provides a URL (usually a `localhost:8787`) to review your Worker. The browser prints your value when you visit the URL provided by Wrangler.
-
-The browser should simply return the `VALUE` corresponding to the `KEY` you have specified with the `get()` method.
-
 </TabItem><TabItem label = 'Dashboard'>
 
 <Steps>
@@ -388,25 +392,14 @@ The browser should simply return the `VALUE` corresponding to the `KEY` you have
 3. Select **Edit Code**.
 4. Clear the contents of the `workers.js` file, then paste the following code.
 
-	```js
-	export default {
-		async fetch(request, env, ctx) {
-			try {
-				await env.BINDING_NAME.put("KEY", "VALUE");
-				const value = await env.BINDING_NAME.get("KEY");
-				if (value === null) {
-					return new Response("Value not found", { status: 404 });
-				}
-				return new Response(value);
-			} catch (err) {
-				// In a production application, you could instead choose to retry your KV
-				// read or fall back to a default code path.
-				console.error(`KV returned error: ${err}`);
-				return new Response(err.toString(), { status: 500 });
-			}
-		},
-	};
-	```
+	<GitHubCode
+			repo="cloudflare/docs-examples"
+			file="kv/kv-get-started/src/index.ts"
+			commit="831724c421748229864c1ea28c854e352c62625e"
+			lang="ts"
+			lines="1-26"
+			useTypeScriptExample={true}
+	/>
 
 	The code above:
 
@@ -423,13 +416,38 @@ The browser should simply return the `VALUE` corresponding to the `KEY` you have
 
 ## 6. Deploy your KV
 
+You can deploy your project in one of two ways:
+
+- **Locally:** Runs from your machine on a local server. The URL to your web application is only accessible while you are running the application from your terminal.
+- **Remotely:** Runs on Cloudflare's global network. The URL to your web application will be accessible to anyone with the URL.
+
+:::note
+You can only deploy your project locally through the Wrangler CLI. You can only deploy remotely when deploying through the Cloudflare dashboard.
+:::
+
+In this tutorial, we expect the URL to simply return the value `disabled` (which corresponds to the key `user_2`).
+
+### Deploy your project locally
+
+<Steps>
+1. Run the following command within your project directory:
+
+	```sh
+	npm run dev
+	```
+
+2. Visit the URL for your newly created Workers KV application running on your local machine, as provided by Wrangler (usually `localhost:8787`).
+</Steps>
+
+### Deploy your project globally
+
 <Tabs syncKey = 'CLIvsDash'><TabItem label = 'CLI'>
 
 <Steps>
 1. Run the following command to deploy KV to Cloudflare's global network:
 
     ```sh
-    npx wrangler deploy
+    npm run deploy
     ```
 
 2. Visit the URL for your newly created Workers KV application.
