From c1b7410d9d88a62fead635683f876a149741251b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= Date: Sat, 28 Mar 2026 09:09:31 +0100 Subject: [PATCH] docs: phase out prominent http/https specifier examples 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) --- runtime/fundamentals/modules.md | 88 ++++--------------- .../getting_started/command_line_interface.md | 7 -- runtime/reference/cli/run.md | 13 +-- runtime/reference/jsx.md | 7 +- runtime/reference/migration_guide.md | 2 +- runtime/reference/ts_config_migration.md | 14 ++- 6 files changed, 30 insertions(+), 101 deletions(-) diff --git a/runtime/fundamentals/modules.md b/runtime/fundamentals/modules.md index 46e081875..6d4d4e4b3 100644 --- a/runtime/fundamentals/modules.md +++ b/runtime/fundamentals/modules.md @@ -161,12 +161,11 @@ during tests. When working with third-party modules in Deno, use the same `import` syntax as you do for local code. Third party modules are typically imported from a remote -registry and start with `jsr:` , `npm:` or `https://`. +registry and start with `jsr:` or `npm:`. ```ts title="main.ts" import { camelCase } from "jsr:@luca/cases@1.0.0"; import { say } from "npm:cowsay@1.6.0"; -import { pascalCase } from "https://deno.land/x/case/mod.ts"; ``` Deno recommends [JSR](https://jsr.io), the modern JavaScript registry, for third @@ -189,8 +188,7 @@ field the **import map**, which is based on the [Import Maps Standard]. { "imports": { "@luca/cases": "jsr:@luca/cases@^1.0.0", - "cowsay": "npm:cowsay@^1.6.0", - "cases": "https://deno.land/x/case/mod.ts" + "cowsay": "npm:cowsay@^1.6.0" } } ``` @@ -200,7 +198,6 @@ With remapped specifiers, the code looks cleaner: ```ts title="main.ts" import { camelCase } from "@luca/cases"; import { say } from "cowsay"; -import { pascalCase } from "cases"; ``` The remapped name can be any valid specifier. It's a very powerful feature in @@ -320,44 +317,23 @@ Here is an overview of all the ways you can specify a version or a range: ## HTTPS imports -Deno also supports import statements that reference HTTP/HTTPS URLs, either -directly: +Deno supports import statements that reference HTTP/HTTPS URLs: ```js import { Application } from "https://deno.land/x/oak/mod.ts"; ``` -or part of your `deno.json` import map: +This can be convenient for small, single-file scripts that don't need a +`deno.json` file. However, for most projects **we recommend using `jsr:` or +`npm:` specifiers instead**, which provide better versioning, dependency +management, and tooling support (including `deno add` and `deno install`). -```json -{ - "imports": { - "oak": "https://deno.land/x/oak/mod.ts" - } -} -``` - -Supporting HTTPS imports enables us to support the following JavaScript CDNs, as -they provide URL access to JavaScript modules: +:::caution -- [deno.land/x](https://deno.land/x) -- [esm.sh](https://esm.sh) -- [unpkg.com](https://unpkg.com) - -HTTPS imports are useful if you have a small, often single file, Deno project -that doesn't require any other configuration. With HTTPS imports, you can avoid -having a `deno.json` file at all. It is **not** advised to use this style of -import in larger applications however, as you may end up with version conflicts -(where different files use different version specifiers). HTTP imports are not -supported by `deno add`/`deno install` commands. - -:::info - -Use HTTPS imports with caution, and only **from trusted sources**. If the server -is compromised, it could serve malicious code to your application. They can also -cause versioning issues if you import different versions in different files. -HTTPS imports remain supported, **but we recommend using a package registry for -the best experience.** +HTTPS imports do not support version resolution, are not managed by +`deno add`/`deno install`, and can cause versioning issues if different files +reference different URLs. Only use them from **trusted sources** — if the server +is compromised, it could serve malicious code to your application. ::: @@ -433,36 +409,6 @@ Limitations: - The npm package name must exist in the registry, even if you're using a local copy. -### Overriding HTTPS imports - -Deno also allows overriding HTTPS imports through the `scopes` field in -`deno.json`. This feature is particularly useful when substituting a remote -dependency with a local patched version for debugging or temporary fixes. - -Example: - -```json title="deno.json" -{ - "imports": { - "example/": "https://deno.land/x/example/" - }, - "scopes": { - "https://deno.land/x/example/": { - "https://deno.land/x/my-library@1.0.0/mod.ts": "./patched/mod.ts" - } - } -} -``` - -Key points: - -- The `scopes` field in the import map allows you to redirect specific imports - to alternative paths. -- This is commonly used to override remote dependencies with local files for - testing or development purposes. -- Scopes apply only to the root of your project. Nested scopes within - dependencies are ignored. - ## Vendoring remote modules If your project has external dependencies, you may want to store them locally to @@ -509,8 +455,6 @@ Modules can be published to: auto-generates documentation for you - [npm](https://www.npmjs.com/) - use [dnt](https://github.com/denoland/dnt) to create the npm package -- [deno.land/x](https://deno.com/add_module) - for HTTPS imports, use JSR - instead if possible ## Reloading modules @@ -711,8 +655,8 @@ following in a Deno configuration file: ## Supply chain management -Modern JavaScript projects pull code from many sources (JSR, npm, HTTPS URLs, -local workspaces). Good supply chain management helps you achieve four goals: +Modern JavaScript projects pull code from many sources (JSR, npm, local +workspaces). Good supply chain management helps you achieve four goals: - Determinism: everyone (and your CI) runs the exact same code. - Security: unexpected upstream changes or compromises are detected early. @@ -734,8 +678,8 @@ local workspaces). Good supply chain management helps you achieve four goals: 4. Vendor when you need hermetic/offline builds (`"vendor": true`) or when you must patch third‑party code locally. Vendoring does not remove the need for a lockfile—it complements it. -5. Prefer import map (`imports`) entries over raw HTTPS imports in larger - codebases to centralize version changes. +5. Use `jsr:` and `npm:` specifiers with import map (`imports`) entries to + centralize version management. 6. Periodically unfreeze and update consciously (for example on a weekly or sprint cadence) instead of ad‑hoc updates during feature work. diff --git a/runtime/getting_started/command_line_interface.md b/runtime/getting_started/command_line_interface.md index bd980e290..5d6e73d3a 100644 --- a/runtime/getting_started/command_line_interface.md +++ b/runtime/getting_started/command_line_interface.md @@ -36,13 +36,6 @@ relative to the current working directory: deno run main.ts ``` -Deno supports running scripts directly from URLs. This is particularly useful -for quickly testing or running code without downloading it first: - -```shell -deno run https://docs.deno.com/examples/scripts/hello_world.ts -``` - You can also run a script by piping it through standard input. This is useful for integrating with other command-line tools or dynamically generating scripts: diff --git a/runtime/reference/cli/run.md b/runtime/reference/cli/run.md index 6ea0a7bbe..2a89a0033 100644 --- a/runtime/reference/cli/run.md +++ b/runtime/reference/cli/run.md @@ -4,19 +4,12 @@ oldUrl: /runtime/manual/tools/run/ command: run openGraphLayout: "/open_graph/cli-commands.jsx" openGraphTitle: "deno run" -description: "Run a JavaScript or TypeScript program from a file or URL with Deno's runtime" +description: "Run a JavaScript or TypeScript program with Deno's runtime" --- ## Usage -To run [this file](https://docs.deno.com/examples/scripts/hello_world.ts) use: - -```console -deno run https://docs.deno.com/examples/scripts/hello_world.ts -``` - -You can also run files locally. Ensure that you are in the correct directory and -use: +Run a local file: ```console deno run hello-world.ts @@ -77,7 +70,7 @@ console if there are errors while you work. You can pipe code from stdin and run it immediately with: ```console -curl https://docs.deno.com/examples/scripts/hello_world.ts | deno run - +cat main.ts | deno run - ``` ## Terminate run diff --git a/runtime/reference/jsx.md b/runtime/reference/jsx.md index 472637fad..987355a3c 100644 --- a/runtime/reference/jsx.md +++ b/runtime/reference/jsx.md @@ -194,10 +194,10 @@ using the default "legacy" configuration, you can add the JSX import source pragma to a `.jsx` or `.tsx` module, and Deno will respect it. The `@jsxImportSource` pragma needs to be in the leading comments of the module. -For example to use Preact from esm.sh, you would do something like this: +For example to use Preact, you would do something like this: ```jsx -/** @jsxImportSource https://esm.sh/preact */ +/** @jsxImportSource preact */ export function App() { return ( @@ -208,6 +208,9 @@ export function App() { } ``` +This requires `preact` to be mapped in your `deno.json` import map (e.g. +`"preact": "npm:preact@^10"`). + ### `jsxImportSourceTypes` In certain cases, a library may not provide types. To specify the types, you can diff --git a/runtime/reference/migration_guide.md b/runtime/reference/migration_guide.md index 57c63073d..6faddc6ff 100644 --- a/runtime/reference/migration_guide.md +++ b/runtime/reference/migration_guide.md @@ -149,7 +149,7 @@ import { denoPlugins } from "jsr:@luca/esbuild-deno-loader"; const result = await esbuild.build({ plugins: [...denoPlugins()], - entryPoints: ["https://deno.land/std@0.185.0/bytes/mod.ts"], + entryPoints: ["./main.ts"], outfile: "./dist/bytes.esm.js", bundle: true, format: "esm", diff --git a/runtime/reference/ts_config_migration.md b/runtime/reference/ts_config_migration.md index bf55e980b..dcce176f8 100644 --- a/runtime/reference/ts_config_migration.md +++ b/runtime/reference/ts_config_migration.md @@ -394,7 +394,7 @@ means it requires an extension, and is relative to the module referencing it. It can be a fully qualified URL as well: ```ts -/// +/// ``` ### Supplying "types" in deno.json @@ -407,7 +407,6 @@ your `deno.json`. For example: "compilerOptions": { "types": [ "./types.d.ts", - "https://deno.land/x/pkg@1.0.0/types.d.ts", "/Users/me/pkg/types.d.ts" ] } @@ -485,13 +484,10 @@ file, its resolution follow the normal import rules of Deno. For a lot of the `.d.ts` files that are generated and available on the web, they may not be compatible with Deno. -[esm.sh](https://esm.sh) is a CDN which provides type declarations by default -(via the `X-TypeScript-Types` header). It can be disabled by appending `?no-dts` -to the import URL: - -```ts -import React from "https://esm.sh/react?no-dts"; -``` +When using HTTPS imports from CDNs like [esm.sh](https://esm.sh), type +declarations are provided by default (via the `X-TypeScript-Types` header). This +can be disabled by appending `?no-dts` to the import URL. Note that for most +use cases, `npm:` specifiers are the recommended way to import npm packages. ## Behavior of JavaScript when type checking