Skip to content

Drop the unused @playground example tag - #3511

Merged
piscisaureus merged 2 commits into
mainfrom
drop-playground-tag
Nov 12, 2026
Merged

piscisaureus merged 2 commits into
mainfrom
drop-playground-tag

Conversation

@piscisaureus

@piscisaureus piscisaureus commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

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.

Drive-by: the key={i} on <SnippetComponent> in the same file failed
deno check (the component declares no key prop, and Lume's static
JSX has no use for one); it is dropped.

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 avocet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Dead-code removal of the @playground tag (commit 089e35c8). 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: the playground?: string field on the Example interface (examples/types.ts), the playground: kvs.playground assignment in the parser (examples/utils/parseExample.ts), and the JSX block that rendered the link (examples/_components/ExamplePage.tsx).

  2. Removal of key={i} from a mapped component (commit 28ee4130). In ExamplePage.tsx, the <SnippetComponent> rendered inside file.snippets.map((snippet, i) => …) loses its key={i} prop. This is an unrelated cleanup bundled into the PR; the component does not declare a key prop.

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 .playground member 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:

  1. Pure build-time string SSR — key is never consulted. The repo sets "jsxImportSource": "lume" (deno.json:63), and lume/jsx-runtime resolves to oscarotero/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. key is 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.
  2. SnippetComponent is not an interactive island. It is a plain SSR function component (examples/_components/SnippetComponent.tsx) that runs Prism.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.
  3. No CI gate can fail on this. The Lint workflow (.github/workflows/lint.yml) runs deno fmt --check and deno task test — it does not run deno lint, so no jsx-key-style rule is enforced in CI (and such a rule is not in Deno's default recommended set regardless). key is a special JSX prop outside SnippetComponent'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 @playground path is confirmed dead, and the key removal 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 test and deno fmt --check still 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.

@piscisaureus
piscisaureus merged commit b4639c3 into main Nov 12, 2026
3 checks passed
@piscisaureus
piscisaureus deleted the drop-playground-tag branch November 12, 2026 17:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants