Skip to main content
Deno 2 is finally here 🎉️
Learn more
Why Deno's HTTP imports struggle at scale

What we got wrong about HTTP imports

Everything should be made as simple as possible, but not simpler.

Albert Einstein

From the beginning, HTTP imports have been a key feature of Deno. For years, this was the entire module system, aimed at simplifying JavaScript development by using the web’s distributed nature, unlike npm’s centralized registry.

For example, you can import the assertEquals() function from the standard library like this:

import { assertEquals } from "https://deno.land/std@0.224.0/assert/mod.ts";

assertEquals(1, 2);

This idea was game-changing (and still can be). We pursued it hard, before eventually realizing: this design decision came with significant tradeoffs.

Let’s explore why this approach doesn’t scale with project complexity as well as we’d originally hoped, and how Deno recommends sharing and consuming modules today to overcome these challenges.

The Dream

Designing Deno’s module system around HTTP imports was ambitious. It aimed to replace npm with a distributed system over HTTP, aligning with how ES Modules work in browsers. This eliminated the need for package.json files and node_modules folders, simplifying project structures. Deno scripts could scale down to single-file programs without a project directory or configuration. Unlike npm, which downloads large tarballs, HTTP imports fetch only the necessary source code. Private registries simply become authenticated proxies.

We integrated this deeply into Deno’s workflows, including caching, preloading, and reloading. We also built deno.land/x, a registry to connect a git repo and share it over HTTP, complete with features like generated documentation.

The Reality

Despite its promise, several issues with HTTP imports emerged since that initial implementation.

Length of URLs

Long URLs clutter codebases, especially in larger projects. Compare:

import express from "express"; // Node

import oak from "https://deno.land/x/oak@v16.1.0"; // Deno 1.x

Node’s import is clearly shorter (and much more memorable).

Dependency management

Managing long URLs and versions becomes increasingly tedious as projects grow.

Initially, we embraced the deps.ts convention to centralize dependencies in a single file in a project:

// deps.ts
export { concat } from "https://deno.land/std@0.200.0/bytes/mod.ts";
export * as base64 from "https://deno.land/std@0.200.0/encoding/base64.ts";

Then, dependencies could be imported like this:

import { concat } from "../../deps.ts";

While this works, it’s cumbersome compared to a simple package.json file.

Duplicate dependencies

URLs lack semantic versioning, making it hard to manage dependencies.

Although version strings can be embedded in URLs (e.g., https://deno.land/std@0.224.0/fs/copy.ts), HTTP imports lock you in to just one exact version until and unless you manually update the URL. In larger projects, this means you can easily wind up with several variants of the same library in your codebase (which of course is very rarely necessary or beneficial in practice).

Semantic versioning helps deduplicate dependencies, reducing the number of loaded modules. Ideally, Deno should recognize interchangeable modules, using the latest version.

Reliability

The decentralized module system also caused reliability problems. Many modules were hosted on random websites or personal servers, leading to uptime issues. While these servers going down did not immediately make the Deno programs go down (because we cache remote dependencies), it could brick CI and new deployments. And while Deno ensures high availability for its deno.land/x registry, it can’t control other hosts, making overall availability dependent on the least reliable host in your dependency graph.

The solution

To address all of the issues above, Deno’s introduced two major improvements: Import Maps, and JSR.

Turning the Corner with Import Maps and JSR

Let us be clear: Deno is not removing HTTP imports. We still believe in their usefulness. However, it’s become obvious more structure is often needed.

We are committed to improving the JavaScript ecosystem by simplifying how code is written and distributed. JavaScript, essentially the default programming language, deserves a great module system.

Part of that solution is import maps, another web standard from the browser, implemented in Deno. Import maps allow you to get short and memorable specifiers back and manage versions across many files:

{
  "imports": {
    "$ga4": "https://raw.githubusercontent.com/denoland/ga4/main/mod.ts",
    "$marked-mangle": "https://esm.sh/marked-mangle@1.0.1",
    "@astral/astral": "jsr:@astral/astral@^0.4.0",
    "@fresh/plugin-tailwind": "./plugin-tailwindcss/src/mod.ts",
    "@luca/esbuild-deno-loader": "jsr:@luca/esbuild-deno-loader@^0.10.3"
  }
}

On their own, however, import maps don’t solve the semantic versioning problem or the reliability problem—that’s where JSR comes in.

We created JSR as a centralized repository that understands semver, to address the remaining two issues:

  • JSR avoids the reliability problem of depending on multiple hosts to serve modules; and
  • JSR avoids the duplicate dependency problem using semantic versioning (similar to how package.json works in Node with npm).

We believe this new registry will vastly simplify how JavaScript is consumed and shared. While it is admittedly a bit more complex than HTTP imports, we feel the benefits are worth the tradeoffs.

What is JSR?

We launched JSR in March. JSR is an open-source, cross-runtime code registry that allows users to easily share modern JavaScript and TypeScript. It’s built to be reliable and cheap to host, essentially acting as a heavily cached file server due to immutability guarantees.

JSR understands and enforces semantic versioning, solving the duplicate dependency problem. A centralized repository also allows us to provide many improvements that wouldn’t be possible otherwise, from simple publishing of TypeScript to package scoring that encourages best practices. (You can read more about JSR here and why we built JSR here.)

Under the hood, JSR still uses HTTP imports. For example, take this specifier:

jsr:@luca/flag

The above can really just be thought of as a smart redirect to:

https://jsr.io/@luca/flag/1.0.0/mod.ts

This means JSR inherits the parts of HTTP imports that are really great. For example: granular downloads of only the code that is actually being imported (no large tarballs!). Because users are not exposed to these HTTP imports directly however, problems such as long URLs and manual string management go away.

What This Means for Modern Deno

Existing Deno scripts with HTTP imports will continue to work—they’re great for projects of a certain scale. However, we now recommend using import maps instead of deps.ts, and JSR over deno.land/x and/or npm.

So, coming back to the assert example from above: you’ll find it’s much more terse in this new system. And because of semver resolution, dependencies automatically stay up to date (as long as they are not pinned by a lockfile)!

// ❌ Deno 1.x:
import { assertEquals } from "https://deno.land/std@0.224.0/assert/mod.ts";

// ✅ Deno 2
import { assertEquals } from "jsr:@std/assert@1";

assertEquals(1, 2);

When used in a larger project, you can optionally add an import map to make the import specifier shorter, and managing versions across files easier. Then the assert example looks even more terse:

import { assertEquals } from "@std/assert";
assert(1, 2);
{
  "imports": {
    "@std/assert": "jsr:@std/assert@1"
  }
}

It’s up to you when or if you opt in to this approach. We value the ability of Deno scripts to scale down to single files (without deno.json configuration), so it’s important that the import map is completely optional.

Deno 2 is around the corner

JavaScript deserves a simple module system aligned with browser standards. We want to level up the ecosystem, and help it become the industry bedrock we believe it will inevitably become.

To get there, we need good design, and good design requires iteration—we must honestly examine the problems and address them.

Solving these problems defines many of the changes in Deno 2:

  • JSR for sharing modules instead of random file servers
  • semver for versioning Deno packages
  • import maps for managing dependencies

There are a few other properties of Deno 2 that we haven’t discussed:

  • workspaces and monorepo support, landed in Deno 1.45
  • deep Node/npm compatibility including N-API support and compatibility with Next.js

We’ll be releasing Deno 2 in September this year (for real this time).

I’m excited to see how people make use of the next generation of the simple-as-possible-but-not-simpler JavaScript toolchain.

🚨️ Deno 2 is right around the corner 🚨️

There are some minor breaking changes in Deno 2, but you can make your migration smoother by using the DENO_FUTURE=1 flag today.