Improve "you must designate a preview_id for each KV namespace" error to direct users to a solution

[ispivey]

💡 Feature request

With the introduction of preview namespaces, users may run wrangler dev or wrangler preview and see an error like Error: In order to preview a worker with KV namespaces, you must designate a preview_id for each KV namespace you'd like to preview.

However, we've heard from users who weren't sure what to do next: how do you designate a preview_id for each KV namespace?

We should try and see if there's an easy way to make that error message more instructive about how to solve the problem, by directing the user to add a preview id in wrangler.toml, or checking out the docs, or something else.

[veikkoeeva]

Sorry for barging here afterwards like this, but I opened a SO question about this very thing at https://stackoverflow.com/questions/63332306/what-are-cloudflare-kv-preview-ids-and-how-to-get-one.

The problem is that it's not clear what these identifiers really are and how they relate to what gets deployed. It appears the official documentation at https://developers.cloudflare.com/workers/tooling/wrangler/configuration/#kv_namespaces.

Could someone clarify here or in SO, please? :)

[EverlastingBugstopper]

I've answered on the SO post but I'll xpost here:

---

wrangler asks to add a preview_id to the KV namespaces. Is this an identifier to an existing KV namespace?

Yes! The reason there is a different identifier for preview namespaces is so that when developing with wrangler dev or wrangler preview you don't accidentally write changes to your existing production data with possibly buggy or incompatible code. You can add a --preview flag to most wrangler kv commands to interact with your preview namespaces.

---

For your situation here there are actually a few things going on.

1. You are using Workers Sites
2. You have a KV namespace defined in wrangler.toml

Workers Sites will automatically configure a production namespace for each environment you run wrangler publish on, and a preview namespace for each environment you run wrangler dev or wrangler preview on. If all you need is Workers Sites, then there is no need at all to specify a kv-namepsaces table in your manifest. That table is for additional KV namespaces that you may want to read data from or write data to. If that is what you need, you'll need to configure your own namespace and add id to wrangler.toml if you want to use wrangler publish, and preview_id (which should be different) if you want to use wrangler dev or wrangler preview.

[Mrkezii]

I've answered on the SO post but I'll xpost here:

wrangler asks to add a preview_id to the KV namespaces. Is this an identifier to an existing KV namespace?

Yes! The reason there is a different identifier for preview namespaces is so that when developing with wrangler dev or wrangler preview you don't accidentally write changes to your existing production data with possibly buggy or incompatible code. You can add a --preview flag to most wrangler kv commands to interact with your preview namespaces.

For your situation here there are actually a few things going on.

1. You are using Workers Sites
2. You have a KV namespace defined in wrangler.toml

Workers Sites will automatically configure a production namespace for each environment you run wrangler publish on, and a preview namespace for each environment you run wrangler dev or wrangler preview on. If all you need is Workers Sites, then there is no need at all to specify a kv-namepsaces table in your manifest. That table is for additional KV namespaces that you may want to read data from or write data to. If that is what you need, you'll need to configure your own namespace and add id to wrangler.toml if you want to use wrangler publish, and preview_id (which should be different) if you want to use wrangler dev or wrangler preview.

Can this please be added to the docs in a more conspicuous/obvious way ? I mean the portion that implies that one should add the --preview flag when creating the KV namespace to create the preview ID as well

[qiuxin]

Thanks. It works I Run command with --preview.

"wrangler kv:namespace create --preview "Boston"

🌀Creating namespace with title "my-app-Boston_preview"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{ binding = "Boston", preview_id = "479aef3d53b14a718ee9dfed30797cc2" }"