Skip to content

docs: phase out prominent http/https specifier examples#3006

Open
bartlomieju wants to merge 1 commit into
mainfrom
docs/phase-out-https-specifiers
Open

docs: phase out prominent http/https specifier examples#3006
bartlomieju wants to merge 1 commit into
mainfrom
docs/phase-out-https-specifiers

Conversation

@bartlomieju
Copy link
Copy Markdown
Member

Summary

  • Remove most HTTP/HTTPS URL import examples across runtime docs, replacing them with jsr: and npm: specifiers
  • Condense the "HTTPS imports" section in modules.md to a single brief reference with a caution note
  • Remove the "Overriding HTTPS imports" subsection entirely
  • Update code examples in CLI docs, JSX, TypeScript config, and migration guide to use local files or npm: specifiers

Test plan

  • Verify no broken internal links from removed sections
  • Confirm the remaining HTTPS imports section in modules.md reads well as a standalone reference
  • Check that JSX pragma example with import map note is clear

🤖 Generated with Claude Code

Reduce visibility of HTTP/HTTPS URL imports across runtime docs in
favor of jsr: and npm: specifiers. Keeps a single condensed reference
section in modules.md for discoverability.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown
Contributor

@fibibot fibibot left a comment

Choose a reason for hiding this comment

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

runtime/reference/ts_config_migration.md line 397 now shows /// <reference types="./types.d.ts" /> — identical to the example three lines above. The prose between them still reads "It can be a fully qualified URL as well:", so the second code block needs to actually be a URL (swap the deno.land/x example for an npm: or https://esm.sh/... one), or the surrounding sentence needs to be rewritten. As-is the page contradicts itself.

  • nit: runtime/fundamentals/modules.md:323 keeps https://deno.land/x/oak/mod.ts as the canonical HTTPS-imports example, but elsewhere this repo recommends jsr:@oak/oak. A neutral CDN example would avoid the mixed signal.
  • nit: runtime/reference/ts_config_migration.md:487-490 still describes esm.sh's X-TypeScript-Types header but now closes with "for most use cases, npm: specifiers are the recommended way" — fine, but no npm: example is shown for the type-resolution case it was illustrating.

Copy link
Copy Markdown
Contributor

@lunadogbot lunadogbot left a comment

Choose a reason for hiding this comment

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

One blocker remains:

  1. /// <reference types="./types.d.ts" /> on line 397 contradicts the sentence immediately above it: the text says this example can be a fully qualified URL, but it now repeats the same relative-path example from line 389. Please restore a URL example or rewrite the sentence so the duplicate block is intentional.
  • nit: https://deno.land/x/oak/mod.ts is still the canonical HTTPS import in runtime/fundamentals/modules.md; a neutral URL would avoid the mixed signal after this PR removes deno.land/x elsewhere.

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.

3 participants