Docs: document jsr:/https: imports and non-local pinning convention in user-facing manual
Opened by stack72 · 4/21/2026· Shipped 4/21/2026
Gap
The user-facing manual at content/manual/ currently only documents npm: imports for extensions:
- content/manual/reference/extension-manifest.md — doesn't discuss specifier kinds at all.
- content/manual/how-to/create-and-publish-extension.md — only shows import { z } from "npm:zod@4" as an example; no mention of jsr: or https:.
What changed upstream
swamp-club #143 (First-class jsr: specifier support in extension bundler) verified empirically that jsr: and https: specifiers are already first-class — resolved and inlined by deno bundle identically to npm:. The swamp repo's design/extension.md and .claude/skills/swamp-extension-publish/references/publishing.md now document this in the PR accompanying #143. The user-facing manual lags behind.
Suggested content
For reference/extension-manifest.md (or wherever specifier kinds are discussed):
Extensions can use any Deno-compatible import — npm:, jsr:, or https:. All three are resolved and inlined by the bundler identically; zod is the sole externalization exception. Bare specifiers (e.g. from "zod") require a deno.json import map or a package.json with node_modules.
For how-to/create-and-publish-extension.md:
Pin versions on all non-local imports for reproducibility:
- npm:lodash-es@4.17.21
- jsr:@std/assert@1.0.0
- https://deno.land/std@0.224.0/async/delay.ts (version in the URL)
Unpinned specifiers resolve to the registry's current "latest" at push time, so the published bundle silently changes whenever the upstream package publishes a new version.
References
- swamp-club #143
- swamp's design/extension.md — ### Bundles and ## Import Resolution sections (updated in the #143 PR)
- .claude/skills/swamp-extension-publish/references/publishing.md — ### Import Rules (updated in the #143 PR)
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.