cloudflare / cloudflare/developer-platform

Deploy to Cloudflare: pre-fill Vectorize index params + skip blank-OK secrets

Open
#28 3 comments 1 reaction 0 assignees View on GitHub
feature:auto-provisioning polish product:d1 product:vectorize
Dominant language
No language data
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Summary

Two small gaps in the **Deploy to Cloudflare** form that make zero-config templates harder to ship than they should be. Both surface as friction for end-users clicking the deploy button on AI-shaped templates.

Filing this on the back of [office-town-cloud](https://github.com/jezweb/office-town-cloud) — a six-MCP-server Worker + Goose extension where the goal is "click button → answer no questions → working deployment". The button gets us 90% of the way and then trips on two specific spots.

## Gap 1 — Vectorize: form leaves `Dimensions` + `Metric` blank with no way to default from config

The form currently shows empty `Dimensions` and `Metric` fields when a Vectorize binding is declared in wrangler.jsonc, and refuses to deploy until the user fills them in. This is empirically the case as of [wrangler 4.95.0 / config-schema.json](https://github.com/cloudflare/workers-sdk/blob/main/packages/wrangler/config-schema.json):

\`\`\`json
\"vectorize\": {
\"items\": {
\"properties\": {
\"binding\": ...,
\"index_name\": ...,
\"remote\": ...
},
\"required\": [\"binding\", \"index_name\"],
\"additionalProperties\": false
}
}
\`\`\`

The schema explicitly forbids `dimensions` / `metric` / `preset` as inline fields, so a template author can't tell the deploy flow \"this index needs 768/cosine\".

**Concrete case**: Office Town uses Workers AI's `@cf/baai/bge-base-en-v1.5` for semantic search — that's 768 dimensions, cosine metric, locked by the model. There's no other valid value for our template. Users hit the form, see empty fields with no hint, get stuck or guess. The fact that `wrangler vectorize create --preset @cf/baai/bge-base-en-v1.5` already auto-fills these means the data path exists; it just isn't reachable from the deploy button.

I noticed [#13352](https://github.com/cloudflare/workers-sdk/pull/13352) adds interactive prompts for these in wrangler CLI flows — same need, different surface.

**Proposed fix** — allow any of these in the wrangler.jsonc Vectorize binding, plumbed into the deploy form as pre-filled values:

\`\`\`jsonc
\"vectorize\": [{
\"binding\": \"VECTOR_INDEX\",
\"index_name\": \"office-town-vec\",
\"dimensions\": 768, // pre-fills the form field
\"metric\": \"cosine\", // pre-fills the form field
// OR shorthand:
\"preset\": \"@cf/baai/bge-base-en-v1.5\"
}]
\`\`\`

The end-user still sees the values and can edit them; they just start populated instead of empty.

## Gap 2 — Secrets in `.dev.vars.example` are treated as required, no way to mark optional

Every line in `.dev.vars.example` surfaces in the deploy form as a secret field that **blocks deploy if left blank**. This makes it impossible to ship a template where a secret is genuinely optional — for example: a token that the worker auto-generates on first request and stores in D1.

**Concrete case**: Office Town's `MCP_BEARER_TOKEN` is auto-generated by the worker on first request (D1 row, with explicit override available via `wrangler secret put`). The user never needs to provide one at deploy time. But because `MCP_BEARER_TOKEN=` appeared in `.dev.vars.example` (where it belongs for local-dev users), the deploy form demanded a value and would not let the user click Deploy with the field blank. We had to delete `.dev.vars.example` entirely to bypass this — losing the local-dev template benefit just to fix the deploy form.

We also added `package.json > cloudflare.bindings..description` per [the docs](https://developers.cloudflare.com/workers/platform/deploy-buttons/) with text saying \"Leave blank — auto-generates on first request\". The description does appear in the form, but the **required-non-empty validation still fires** regardless of what the description says. So users read \"Leave blank\" and then can't.

**Proposed fix** — pick any of these (in increasing implementation effort):

1. **Lightest**: respect a `# OPTIONAL` comment marker above a line in `.dev.vars.example`:

\`\`\`
# OPTIONAL — worker auto-generates on first request
MCP_BEARER_TOKEN=
\`\`\`

2. **Cleaner**: add a `required` boolean to `package.json > cloudflare.bindings.`:

\`\`\`json
\"cloudflare\": {
\"bindings\": {
\"MCP_BEARER_TOKEN\": {
\"description\": \"Optional — worker auto-generates on first request\",
\"required\": false
}
}
}
\`\`\`

3. **Most flexible**: treat any `NAME=` line whose **value is non-empty** as a default (\"prefill with this, user can edit\") and any line whose value is `=` blank as either:
- required by default (current behaviour), OR
- optional if marked via the `# OPTIONAL` comment OR `required:false` flag

## Why this matters

Both gaps push otherwise-zero-config templates into needing **out-of-band instructions in the README/docs** to tell users \"fill this field with this exact value\" or \"actually leave this field blank, just trust us\". That's a UX regression — the whole point of the deploy button is that users don't need to read docs first.

For AI-shaped templates specifically (Vectorize-backed), the Vectorize fields are arguably the **most common deploy-form gotcha**: every embedding-based template needs specific dimensions/metric tied to the model used in code.

## Workaround in place today

For office-town-cloud we currently:
- Document `Dimensions=768 + Metric=cosine` prominently in three places (README, INSTALL.md, wrangler.jsonc comment)
- Deleted `.dev.vars.example` so the four secret fields don't appear in the form
- Auto-generate the bearer at runtime; document the optional secrets as `wrangler secret put NAME` post-deploy chores

It works, but every template author hits the same workaround. Filing this so future templates don't have to.

## Versions

- Tested with wrangler `4.95.0` and the deploy form at `deploy.workers.cloudflare.com` as of 2026-05-28.
- Account on Workers Paid plan (Containers beta — separate but related: Containers in templates work great via the button, full credit there).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.