Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Modules and Permissions

JSR and npm Packages

Use packages in Deno from JSR and npm with jsr: and npm: specifiers, version ranges, node_modules and package.json support, deno install, publishing to JSR and Node compatibility tips.

Libraries are where most programs spend their lines of code. Deno can import from several sources, but two matter most for new code: JSR, the JavaScript Registry built for TypeScript and ES modules, and npm, the registry with over two million packages. This lesson shows how to use both, how version ranges work, and when Deno creates a node_modules folder.

The deno commands here are read-only on this site. The runnable examples parse and compare specifiers and version ranges, which are the rules Deno applies.

JSR packages

JSR packages are named @scope/name. Import them with a jsr: specifier that includes a version:

TypeScript
import { join } from "jsr:@std/path@1";
import { assertEquals } from "jsr:@std/assert@^1.0.0";
import { parseArgs } from "jsr:@std/cli@1/parse-args"; // a sub-path

The version after @ is a range. Add the package to your project once with deno add, and later files use the short name:

Terminal
deno add jsr:@std/path
TypeScript
import { join } from "@std/path"; // mapped by deno.json

JSR ships TypeScript source and generates documentation and type declarations. It scores every package (docs, types, runtime support), and it works on Deno, Node.js, Bun and browsers. The standard library is on JSR as @std/*, which is why you see it everywhere.

npm packages

The npm: specifier loads any package from the npm registry:

TypeScript
import chalk from "npm:chalk@5";
import express from "npm:express@4";
import { z } from "npm:zod@3";

console.log(chalk.green("works"));

Deno downloads the package and its dependencies into the global cache. It then runs them with its Node compatibility layer. No npm install step, no node_modules folder by default.

If the package ships its own types, they are used for checking. For packages with types in a separate @types/... package, Deno finds them automatically in most cases; you can also point to them with a // @deno-types="npm:@types/foo" comment.

For Node built-in modules, use the node: prefix: import fs from "node:fs". Deno 2 requires the prefix.

Version ranges

Both registries use semantic versioning. The common range forms are:

Range Meaning Allows
1.2.3 exactly that version 1.2.3
^1.2.3 compatible: same major 1.2.3 up to below 2.0.0
~1.2.3 patch updates 1.2.3 up to below 1.3.0
1 any 1.x 1.0.0 up to below 2.0.0

Inside deno.json, deno add writes ^ ranges. In inline specifiers, a bare @1 means "any 1.x". The lock file records the exact versions chosen, so everyone installing gets the same ones.

Let us parse specifiers the way a tool would. The function below splits jsr: and npm: strings into registry, name, version and sub-path.

Node.js Parsing package specifiers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A range like ^1.2.3 is easy to test by hand. This small checker handles the caret and tilde forms:

Node.js Does a version satisfy a range?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

(Real semver has more rules, such as ^0.x and pre-releases; use @std/semver for production code.)

node_modules and package.json

Many projects already use package.json. Deno 2 understands it:

JSON
{
  "name": "my-app",
  "dependencies": { "express": "^4.21.0" }
}

With that file in place, import express from "express" works, and Deno resolves the name from the dependency list. Deno creates a node_modules folder when it needs one, controlled by the nodeModulesDir setting in deno.json:

Setting Behaviour
"none" no folder; global cache only (default when there is no package.json)
"auto" create and maintain a local folder on run
"manual" use a folder you populated with deno install (default with package.json)
Terminal
deno install               # install dependencies from deno.json / package.json
deno install npm:left-pad  # add and install a package
deno outdated              # list newer versions
deno outdated --update     # update ranges

Frameworks that expect a real node_modules (some bundlers, native packages) need "nodeModulesDir": "auto". Lifecycle scripts such as postinstall are not run by default for safety; allow them for chosen packages with --allow-scripts=npm:package.

Choosing where to import from

flowchart TD
  A["Need a library"] --> B{"In the standard library?"}
  B -->|Yes| C["jsr:@std/..."]
  B -->|No| D{"Published on JSR?"}
  D -->|Yes| E["jsr:@scope/name"]
  D -->|No| F{"On npm?"}
  F -->|Yes| G["npm:name"]
  F -->|No| H["Pinned https URL, or write it"]

Prefer the most verified source that has what you need.

Prefer, in order: the standard library, JSR, npm, then a pinned URL. And always keep an eye on how many dependencies you pull in: every package is code you now trust.

Publishing your own package to JSR

When a module is useful to others, publish it. The package's deno.json needs three fields:

JSON
{
  "name": "@me/greeter",
  "version": "0.1.0",
  "exports": "./mod.ts"
}
Terminal
deno publish --dry-run   # checks types, slow-type rules and docs
deno publish             # publishes to jsr.io (requires a JSR account)

JSR requires explicit types on exported functions (the "no slow types" rule), which lets it generate fast documentation and .d.ts files. Add a doc comment on each export; they become your package's documentation page.

Compatibility tips

  • If an npm package fails, read the error first: missing node: built-ins, native addons (.node files) and unsupported flags are the usual causes.
  • Pin npm versions in deno.json, not just npm:pkg, so installs are repeatable.
  • For CommonJS packages, Deno handles require inside the package; your own code should still use import.
  • Check the Deno vs Node.js lesson for the other differences.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which specifier imports the express package from npm?

    npm: is the prefix for npm packages; jsr: is for JSR and node: for built-in Node modules.
  2. 2. What does ^1.2.3 allow?

    The caret allows updates that keep the major version the same.
  3. 3. Which command adds a JSR package to deno.json?

    deno add writes the dependency into the imports field.
  4. 4. What is the default for lifecycle scripts like postinstall?

    For safety, Deno skips npm lifecycle scripts unless you allow them for a package.

Summary

  • jsr: imports from the JavaScript Registry; npm: imports from npm; node: imports Node built-ins.
  • Version ranges: ^ keeps the major, ~ keeps major and minor; deno.lock fixes the exact result.
  • deno add, deno install, deno remove and deno outdated manage dependencies.
  • Deno 2 reads package.json; nodeModulesDir controls the local folder.
  • Prefer std, then JSR, then npm.
  • Publish with deno publish after giving exports explicit types.

Next: Permissions