Repository navigation
Document KV Connect from Node.js on Deno Deploy - #3510
Conversation
The "Using KV in Node.js" page was removed with the Deploy Classic docs because it was written around Classic's KV Connect URLs and dashboard. KV Connect works on Deno Deploy too, with a different endpoint, so the page is back for the current platform: * `@deno/kv` install and usage, with the Deploy KV Connect URL `https://api.deno.com/v2/databases/<Database ID>/connect`, where the database ID is found, and authentication with a personal or organization access token (`DENO_KV_ACCESS_TOKEN` or `accessToken`) * a note on self-hosted `denokv` servers, which speak the same protocol * the "Connect from outside Deno Deploy" section of the KV reference links to it; the KV sidebar lists it again and the redirects that stood in for it are gone; the Classic dashboard screenshot is removed
avocet-bot
left a comment
There was a problem hiding this comment.
Review: #3510 — Document KV Connect from Node.js on Deno Deploy
Reviewed head SHA: 5879dce9b66a57ea0100fabc16cf24d157dcbf6f
Verdict: Approve — no blocking issues.
Review skill evidence
I ran the pr-review-toolkit:code-reviewer subagent (Claude Code PR-review plugin) over the PR at the reviewed head SHA, and independently verified its key claims with gh api against the same SHA (heading/anchor extraction, repo-tree grep for image references, CI status). Both paths agree.
What this PR does (background for a reader new to this repo)
denoland/docs is the Deno documentation site, built with the Lume static-site generator. Two routing mechanisms coexist:
- Lume pages — Markdown files under
deploy/whose frontmatteroldUrldeclares legacy paths that should 301-redirect to the page. oldurls.json— a flat map ofold path → new pathredirects maintained outside the page files.
An invariant falls out of this: a given URL may be served as a live page or claimed as a redirect source, but never both, or the two mechanisms fight.
"Using KV in Node.js" previously existed but was deleted along with the Deploy Classic documentation, because it was written around Classic's KV Connect URLs and dashboard screenshots. This PR brings the page back, rewritten for the current Deno Deploy platform:
deploy/kv/node.md(new, 102 lines) — how to use the@deno/kvnpm client from Node.js to reach a Deno KV database on Deploy via a KV Connect URL (https://api.deno.com/v2/databases/<Database ID>/connect), authenticating with a personal or organization access token (DENO_KV_ACCESS_TOKENenv var or theaccessTokenoption), plus a note that the same client speaks the open KV Connect protocol to a self-hosteddenokvserver.deploy/_data.ts— adds a "Node" entry to the KV sidebar.deploy/reference/deno_kv.md— adds a cross-link from the "Connect from outside Deno Deploy" section to the new page, and bumpslast_modified.oldurls.json— removes two redirect entries (/deploy/kv/node/and/kv/manual/node/).deploy/kv/images/kv-connect.png— deletes the obsolete Classic dashboard screenshot.deno.lock— a large re-resolve (≈1750 additions).
Correctness verification
Every routing and link invariant that could silently break was checked at the reviewed SHA and holds:
-
Forward anchor resolves.
deploy/kv/node.mdlinks to/deploy/reference/deno_kv/#connect-from-outside-deno-deploy. The target file has a real## Connect from outside Deno Deployheading (deploy/reference/deno_kv.md:61); the github-slugger slug of that heading is exactlyconnect-from-outside-deno-deploy. The anchor resolves. (Confirmed directly by extracting headings from the file at head SHA.) -
Reverse cross-link resolves. The new paragraph in
deploy/reference/deno_kv.mdlinks to/deploy/kv/node/, which is precisely where the new page is served. -
Redirect invariant preserved — this is the subtle part.
- Removing
"/deploy/kv/node/": "/deploy/kv/"fromoldurls.jsonis required: had it stayed, the live page at/deploy/kv/node/would be shadowed by a 301 to/deploy/kv/and become unreachable. Correctly removed; no other redirect keys on that path. node.mddeclaresoldUrl: /kv/manual/node/in frontmatter, and the matching"/kv/manual/node/"entry is removed fromoldurls.json. That avoids the forbidden double-claim (a path being both a Lume pageoldUrland anoldurls.jsonsource). Consistent.
- Removing
-
Deleted image has no dangling references. A full repo-tree scan at head SHA finds zero references to
kv-connect.pnganywhere (the onlykv-connecthits are the unrelated KV Connect protocol spec link,kv-connect.md). Safe deletion. -
KV Connect URL is internally consistent. The URL appears twice in
node.md(the code example and the "KV Connect URLs" section) and is byte-identical in both:https://api.deno.com/v2/databases/<Database ID>/connect. -
Frontmatter matches siblings.
node.mdfollows thedeploy/kv/*.mdpattern (last_modified,title,oldUrl), with an addeddescription.last_modified: 2026-11-12matches today.
Non-blocking note
deno.lockchurn is broad and unrelated. The ~1750-line re-resolve adds many transitive specifiers unrelated to this docs change (supabase, oak, hono, better-auth, stripe, resend, sendgrid, aws-sdk, duckdb, …) and includes apreact 10.27.2 → 10.24.3downgrade. Nothing in the new page requires any of this. It is not a correctness problem for the docs, but it bloats the diff and could mask a genuine dependency regression. Consider revertingdeno.lockto keep the PR focused, or confirm the churn is intentional. Not a merge blocker.
CI status at review time
last_modified freshness check— passlint and link check— pass (this is the job that would catch a broken anchor or dead internal link; it is green, corroborating the manual anchor verification above)deploy/deno/docspreview build — pending (does not affect doc correctness)
Bottom line
The documentation content is accurate and the site-integration invariants — anchors, cross-links, redirect add/remove symmetry, sidebar entry, and image deletion — are all verified clean against head SHA 5879dce9b66a57ea0100fabc16cf24d157dcbf6f. The link-check CI is green. No blocking issues; approving. The only caveat worth a maintainer glance is the oversized, unrelated deno.lock drift.
new commit, please re-review
avocet-bot
left a comment
There was a problem hiding this comment.
Review: #3510 — Document KV Connect from Node.js on Deno Deploy
Reviewed head SHA: a3d45a82c16f46d41e882d4ef85a43fd50622270
Verdict: Approve — no blocking issues.
Review skill evidence
I ran the pr-review-toolkit:code-reviewer subagent (Claude Code PR-review plugin) against this PR at head SHA a3d45a82…, focused on the incremental commit, and independently corroborated its claims with gh api reads of the changed file and its cross-link target at the same SHA. Both paths agree.
What this PR does (background for a reader new to this repo)
denoland/docs is the Deno documentation site, built with the Lume static-site generator. Two routing mechanisms coexist: Lume pages (Markdown under deploy/, whose frontmatter oldUrl declares legacy paths that 301 to the page) and oldurls.json (a flat old path → new path redirect map). A URL may be served as a live page or claimed as a redirect source, never both.
The PR resurrects a "Using KV from Node.js" page — deleted alongside the Deploy Classic docs — rewritten for the current platform. It documents using the @deno/kv npm client from Node.js to reach a Deno KV database on Deploy via a KV Connect URL (https://api.deno.com/v2/databases/<Database ID>/connect), authenticating with a personal or organization access token (DENO_KV_ACCESS_TOKEN env var or the accessToken option), and notes the same client speaks the open KV Connect protocol to a self-hosted denokv server. Supporting changes: a "Node" KV-sidebar entry (deploy/_data.ts), a cross-link from deploy/reference/deno_kv.md, removal of two now-obsolete redirects in oldurls.json, deletion of the stale Classic screenshot deploy/kv/images/kv-connect.png, and a large unrelated deno.lock re-resolve.
What changed since the previously-reviewed head (5879dce9)
A single new commit, "Scope the API parity claim and point to the reference for connection details," edits only deploy/kv/node.md:
- Scopes the API-parity claim. The old blanket statement ("the same API available in Deno may be used in Node as well") is replaced with a scoped version: the Deno KV API is available in Node "with one exception: queue operations (
enqueue/listenQueue) are not part of the KV Connect protocol, so they are unavailable over a remote connection," with a pointer to the@deno/kvpackage README for the full support matrix and supported Node.js versions. - De-duplicates connection instructions. The "KV Connect URLs" section no longer repeats how to find the Database ID or create the access token; it now delegates to the reference page's "Connect from outside Deno Deploy" section and notes the same URL/token work from the Deno CLI.
Verification of the incremental change
The review risk in a de-duplication edit is silent information loss: once a page stops repeating instructions and points elsewhere, the target must actually contain what was removed. Checked at head SHA:
-
Anchor still resolves.
node.mdlinks to/deploy/reference/deno_kv/#connect-from-outside-deno-deploy;deploy/reference/deno_kv.md:61has the heading## Connect from outside Deno Deploy, which github-slugger slugs to exactlyconnect-from-outside-deno-deploy. Resolves. -
Delegation is lossless. The reference section genuinely contains both pieces
node.mdstopped repeating: (a) how to find the Database ID ("Each database's ID is shown in the Databases table on the database instance page in the Deno Deploy console") and (b) how to obtain the access token (export DENO_KV_ACCESS_TOKEN=ddo_..., and "Organization access tokens can be created from your organization's settings page"). The reciprocal link back to/deploy/kv/node/is present, so the cross-reference is bidirectional. No information dropped. -
Markdown/frontmatter intact. Frontmatter shape is unchanged (
last_modified,title,description,oldUrl); the two edited paragraphs are well-formed with balanced inline links; code fences anddeno-tabsblocks are untouched.
Minor, non-blocking accuracy note
- The new sentence frames
enqueueandlistenQueuetogether as "not part of the KV Connect protocol." Strictly, the protocol's atomic-write path does carry enqueue mutations, whereaslistenQueue(which needs server-push/dequeue) is the operation with no remote representation. The practical guidance — queue operations are unavailable over a remote connection — is correct, and the page defers to the@deno/kvREADME as the authoritative support matrix, so even if the "not part of the protocol" phrasing is slightly broad forenqueuespecifically, a reader is routed to the canonical source. The claim comes from a Deno maintainer. Not worth blocking or changing; noted only for completeness.
Carried-forward observations (from the prior head, still true)
- Redirect symmetry correct:
oldurls.jsonremovals of/deploy/kv/node/(so the live page isn't 301-shadowed) and/kv/manual/node/(which is now the page's ownoldUrl, avoiding a double-claim) are both right. - Deleted image has no dangling references anywhere in the repo tree at head.
deno.lockchurn (~1750 lines) remains broad and unrelated to the docs change (includes a preact downgrade and many unrelated deps). Not a correctness problem; worth a maintainer glance to confirm it's intentional. Not a blocker.
CI status at review time
last_modified freshness check— passlint and link check— pending (re-running for the new commit; this is the job that validates anchors/internal links). I manually verified the only links touched by this commit resolve; recommend confirming it goes green before merge.deploy/deno/docspreview build — pending (does not affect doc correctness).
Bottom line
The incremental commit is a clean refinement: the scoped parity claim is accurate/defensible, the anchor resolves, and the de-duplication is lossless because the delegation target genuinely contains the Database-ID and token instructions node.md stopped repeating. All routing invariants verified at head SHA a3d45a82c16f46d41e882d4ef85a43fd50622270. No blocking issues; approving. Caveats are the still-pending link-check/build CI and the unrelated deno.lock drift.
The "Using KV in Node.js" page was removed with the Deploy Classic docs
because it was written around Classic's KV Connect URLs and dashboard.
KV Connect works on Deno Deploy too, with a different endpoint, so the
page is back for the current platform:
@deno/kvinstall and usage, with the Deploy KV Connect URLhttps://api.deno.com/v2/databases/<Database ID>/connect, where thedatabase ID is found, and authentication with a personal or
organization access token (
DENO_KV_ACCESS_TOKENoraccessToken)denokvservers, which speak the same protocollinks to it; the KV sidebar lists it again and the redirects that
stood in for it are gone; the Classic dashboard screenshot is removed