Repository navigation
Drop the unused @playground example tag - #3511
Conversation
Example scripts could carry a `@playground <url>` JSDoc tag, rendered as a "Try this example in a Deno Deploy playground" link. The only tags pointed at Deploy Classic playgrounds and were removed with the Classic docs, so the field, its parser branch and the rendering block are dead.
avocet-bot
left a comment
There was a problem hiding this comment.
Review: #3511 — "Drop the unused @playground example tag"
Reviewed head SHA: 28ee4130b9561507c0f014ca8709784688e6090c
Base: main · Verdict: ✅ Approve — no blocking issues.
What this PR changes (context for a reader new to the repo)
This is the Deno documentation website (denoland/docs), built with Lume, a static site generator that runs on Deno. Pages and components are authored as Preact-style JSX but are rendered server-side to static HTML at build time — there is no browser-side virtual DOM, hydration, or reconciliation for the components touched here (confirmed below).
The examples/ subtree powers the "Examples" section of the site. Each example is a small script annotated with JSDoc-style @tag value comments. examples/utils/parseExample.ts parses those tags into a key/value map (kvs) and returns a typed Example object (shape defined in examples/types.ts), which examples/_components/ExamplePage.tsx renders.
The PR contains two logical changes across two commits:
-
Dead-code removal of the
@playgroundtag (commit089e35c8). Historically an example could carry a@playground <url>tag that rendered a "Try this example in a Deno Deploy playground" link. Per the author, the only such tags pointed at Deploy Classic playgrounds, which were deleted along with the Classic docs — so the feature is now dead. The PR removes all three pieces of it: theplayground?: stringfield on theExampleinterface (examples/types.ts), theplayground: kvs.playgroundassignment in the parser (examples/utils/parseExample.ts), and the JSX block that rendered the link (examples/_components/ExamplePage.tsx). -
Removal of
key={i}from a mapped component (commit28ee4130). InExamplePage.tsx, the<SnippetComponent>rendered insidefile.snippets.map((snippet, i) => …)loses itskey={i}prop. This is an unrelated cleanup bundled into the PR; the component does not declare akeyprop.
Assessment
Both changes are safe. Findings below are self-contained.
Change 1 — @playground removal is complete and consistent
Intended behavior after this change: the playground field should no longer exist anywhere, and nothing should read it. Verified against the head SHA on a fresh clone:
grep -rn "playground" examples/→ no matches. The interface field, the parser assignment, and the render block are all gone, with no remaining reader of.playground.grep -rn "@playground"across the whole repo → no matches. No example script or doc still carries the tag, matching the author's claim that the only tags pointed at now-deleted Classic playgrounds.- Repo-wide grep for
.playgroundmember access,playground:, and the literal"Try this example in a Deno Deploy"string across all*.ts/*.tsx→ no matches.
TypeScript remains sound: the object literal returned by parseExample still conforms to the narrowed Example interface (no excess- or missing-property mismatch), and no caller destructures or indexes .playground. Even if a stray @playground tag reappeared in a future example, the parser stores unknown tags generically into kvs and only hard-validates title/tags/difficulty, so such a tag would be silently ignored rather than throw. This is clean, complete dead-code removal with no dangling dependency.
Change 2 — key={i} removal has zero observable effect (not a regression)
Background: In React/Preact, a key on a list item helps the runtime reconcile DOM nodes efficiently when a list is re-rendered, reordered, inserted into, or deleted from. Removing a key from a mapped element is normally worth scrutiny because it can (a) emit a dev-mode "missing key" warning and (b) cause incorrect node reuse during client-side reconciliation.
Neither risk applies here, for three concrete reasons:
- Pure build-time string SSR —
keyis never consulted. The repo sets"jsxImportSource": "lume"(deno.json:63), andlume/jsx-runtimeresolves tooscarotero/ssx@0.1.14(deno.json:15). ssx renders JSX directly to an HTML string at build time; there is no virtual DOM and no reconciliation pass.keyis a reserved JSX prop that ssx does not emit as an HTML attribute, so the generated static HTML is byte-identical with or without it. The change is not observable in output. SnippetComponentis not an interactive island. It is a plain SSR function component (examples/_components/SnippetComponent.tsx) that runsPrism.highlight(...)to produce static markup. It has no client script and is not hydrated, so there is no client-side list reconciliation where a key could matter. The snippet list is also static (never reordered or mutated after build), so even if it were reconciled, an index key and no key would behave identically.- No CI gate can fail on this. The Lint workflow (
.github/workflows/lint.yml) runsdeno fmt --checkanddeno task test— it does not rundeno lint, so nojsx-key-style rule is enforced in CI (and such a rule is not in Deno's default recommended set regardless).keyis a special JSX prop outsideSnippetComponent's declared props, so removing it does not affect type-checking either.
Minor, non-blocking stylistic note (not a defect): the two sibling maps in the same file keep their keys — files.map(… key={file.name}) and additionalResources.map(… key={link + title}) — so after this change the snippet map is the only key-less loop in the component. Because keys are inert in this SSR-only, string-rendered context, this inconsistency has no functional consequence; I mention it only for completeness.
Review focus checklist
- Correctness bugs: none.
- Regressions: none — the
@playgroundpath is confirmed dead, and thekeyremoval produces byte-identical HTML. - Missing tests: not needed — this is dead-code/no-op removal with no new behavior to cover; CI's existing
deno task testanddeno fmt --checkstill gate the change. - Security/privacy: none — no auth, data handling, or external I/O involved.
- Races/concurrency: none — pure build-time rendering.
- Broken edge cases: none identified.
Review skill evidence
I invoked the pr-review-toolkit:code-reviewer agent (Claude Code PR Review Toolkit plugin) against a fresh depth-1 clone checked out at the reviewed head SHA. It independently verified the completeness of the @playground removal and the safety of the key={i} removal (tracing the lume/jsx-runtime → ssx SSR runtime and the CI workflow). I corroborated its load-bearing claims directly: repo-wide greps confirming no remaining playground/@playground references, deno.json confirming jsxImportSource: "lume" → ssx@0.1.14, and .github/workflows/lint.yml confirming CI runs deno fmt --check + deno task test but not deno lint.
Conclusion: Clean dead-code removal plus a harmless key cleanup. Safe to merge.
Example scripts could carry a
@playground <url>JSDoc tag, rendered asa "Try this example in a Deno Deploy playground" link. The only tags
pointed at Deploy Classic playgrounds and were removed with the Classic
docs, so the field, its parser branch and the rendering block are dead.
Drive-by: the
key={i}on<SnippetComponent>in the same file faileddeno check(the component declares nokeyprop, and Lume's staticJSX has no use for one); it is dropped.