Deno
A JavaScript and TypeScript runtime with a package manager, formatter, linter, test runner, type checker, and bundler in one binary. Runs TypeScript directly.
Needs Deno 2.9+. Check with deno --version, update with deno upgrade.
Deno works the way npm and bun do
Deno is not a separate ecosystem to port code into:
deno installreads an existingpackage.jsonand writes a realnode_modules.deno add expressinstalls from npm. Unprefixed names default to npm.deno task buildrunsscripts.buildfrompackage.jsonortasks.buildfromdeno.json. If both define it,deno.jsonwins.- Node built-ins work prefixed or not:
node:fsandfsboth resolve. deno main.jsruns a file.deno runis optional.- Deno reads
tsconfig.json.
Don't tell users to rewrite imports, adopt JSR, or restructure as a precondition. The two real differences are permissions and npm lifecycle scripts not running by default.
Single-file scripts need no build step and no tsconfig.json. Applications and
framework projects keep their normal setup.
To convert an existing project, consult the Node/npm compatibility guidance.
Dependency management
deno install # install everything declared
deno add express # from npm (unprefixed = npm)
deno add jsr:@std/path # from JSR
deno add -D vitest # dev dependency (package.json only)
deno remove express
deno outdated # list outdated deps
deno update # alias for `deno outdated --update`
deno update --latest # ignore existing semver ranges
deno list # declared deps + resolved versions (npm ls)
deno why express # why a package is in the tree
deno audit # vulnerability audit
deno ci # clean reproducible install for CI
dx cowsay hello # run a package binary without installing (npx)
deno ci is the CI command, not deno install: it requires deno.lock,
deletes node_modules, installs strictly from the lockfile, and fails if the
lockfile is stale. --prod skips devDependencies.
dx is npx / bunx / pnpm dlx, and an alias for deno x. It runs with
the sandbox disabled, so treat it with the same care as npx.
Deno won't install a version published less than a day ago, limiting the window
for a compromised release. Override with --min-dep-age, which takes minutes
(120), an ISO-8601 duration (P7D), a cutoff date, or 0 to disable:
deno add --min-dep-age=0 npm:some-package
Lifecycle scripts (postinstall) don't run by default — a common surprise when
a native addon looks broken after install. Approve once per project:
deno approve-scripts # interactive picker
deno install --allow-scripts=npm:better-sqlite3
Where configuration goes
| File | Holds |
|---|---|
package.json |
dependencies, scripts |
tsconfig.json |
TypeScript compiler options |
deno.json |
Deno config: fmt, lint, tasks, workspaces |
Put dependencies in package.json — every other tool reads it, and Deno
resolves it natively. Use deno.json for dependencies only when there is no
package.json: a standalone script, or a JSR package. Likewise prefer
tsconfig.json over compilerOptions in deno.json, so tsc and editors see
the same settings.
Commit deno.lock. Deno seeds it from an existing package-lock.json,
yarn.lock, bun.lock, or pnpm lockfile, preserving pins.
node_modules layout
Deno uses pnpm's isolated layout: real files in node_modules/.deno/, exposed
by symlinks, so a package can't import what it never declared. For a tool that
needs npm's flat hoisted tree:
{ "nodeModulesDir": "manual", "nodeModulesLinker": "hoisted" }
The hoisted linker requires nodeModulesDir: "manual". nodeModulesDir
controls whether Deno creates and manages a local node_modules, including
projects with a package.json; run deno install to populate it in manual mode.
Permissions
deno run grants no filesystem, network, environment, or subprocess access
unless asked. deno eval has all permissions implicitly and does not accept
scoped --allow-* flags. Use deno run with explicit grants when access must
be restricted.
deno run --allow-net=api.example.com --allow-read=./data main.ts
deno run -A main.ts # allow everything
| Flag | Short | Grants |
|---|---|---|
--allow-read[=paths] |
-R |
filesystem read |
--allow-write[=paths] |
-W |
filesystem write |
--allow-net[=hosts] |
-N |
network |
--allow-env[=names] |
-E |
environment variables |
--allow-sys[=apis] |
-S |
OS information |
--allow-import[=hosts] |
-I |
imports from remote hosts |
--allow-run[=bins] |
— | subprocesses |
--allow-ffi[=paths] |
— | native libraries (unstable) |
--allow-all |
-A |
everything |
-S is --allow-sys, not --allow-run. Every flag takes an allowlist —
--allow-net=example.com:443 beats bare --allow-net. Matching --deny-*
flags always win.
On Requires net access to "...", add that specific permission. -A is fine
for trusted first-party code and during migration, but a poor default to commit
in a task.
Configuration
deno.json (or .jsonc) is auto-discovered from the current directory upward.
{
"tasks": {
"dev": "deno watch -A main.ts",
"start": "deno run -A main.ts"
},
"fmt": { "exclude": ["build/"] },
"lint": { "rules": { "exclude": ["no-explicit-any"] } },
"exclude": ["build/", "dist/"]
}
Top-level exclude applies to every subcommand; per-tool exclude narrows it.
deno.json also accepts imports, an import map pointing bare specifiers at
real ones. That is how a project without package.json declares dependencies,
and how a JSR package declares its own alongside name, version, exports.
Workspaces
npm, Yarn, and Bun workspaces work out of the box — Deno reads package.json
"workspaces" directly. pnpm is the exception: pnpm-workspace.yaml is
migrated into deno.json on first run, which must then be re-run.
{ "workspace": ["./packages/core", "./packages/cli"] }
Members can be explicit paths or globs: "packages/*" matches one level,
"packages/*/*" matches two, and "packages/**" recurses. Prefix a pattern
with ! to exclude matching members. Run a task across members with
deno task --filter '*' build.
Packages: npm and JSR
Prefer npm — it is where the ecosystem is, and deno add express is the
normal case. Reach for JSR for the standard library (@std/*), or to publish
TypeScript that consumers get types for without a build step. Mixing is fine.
deno add jsr:@std/path npm:express
deno doc jsr:@std/path # read a package's API from the terminal
Deno once used full URL imports (https://deno.land/x/...). They still run but
aren't recommended; to modernize, deno add the package and import the bare
specifier.
Built-in tooling
deno fmt # format (--check for CI)
deno lint # lint (--fix, --rules)
deno test # tests (--watch, --parallel, --coverage=dir)
deno check main.ts # type-check without running
deno bench # benchmarks
deno coverage # coverage report from --coverage output
deno compile main.ts # single-file executable (--target cross-compiles)
deno doc mod.ts # docs (--html for a site)
deno info main.ts # module graph and cache info
These cover prettier, eslint, jest/vitest, tsc, and pkg/nexe with no config or dependencies — but they are not drop-in replacements. Parity is incomplete, so moving an established project is real work. There is no need to migrate: keep prettier, eslint, and vitest, and use Deno as runtime and package manager. Prefer the built-in tools for new projects.
Suppress with // deno-lint-ignore <rule>, // deno-lint-ignore-file,
// deno-fmt-ignore, // deno-fmt-ignore-file. In Markdown,
<!-- deno-fmt-ignore --> before a code block protects illustrative snippets
that aren't valid standalone code.
Running code
deno main.ts # deno run is optional
deno watch main.ts # reload on change (replaces nodemon)
deno task dev # task from package.json or deno.json
deno repl
deno eval "console.log(1)"
deno watch hot-replaces modules, restarting if that fails; it aliases
deno run --watch-hmr.
An HTTP server needs no dependencies:
Deno.serve((_req) => new Response("Hello"));
Starting a new project
Scaffold rather than hand-writing the files:
deno init my-project # script + test + deno.json
deno init --empty my-project # just main.ts and deno.json
deno init --lib my-lib # library laid out for JSR
deno create npm:vite -- my-app # scaffold from a package initializer
deno create is npm create / yarn create and covers that ecosystem
(deno create npm:astro, etc). Use an npm: or jsr: prefix, or select
unprefixed names with --npm or --jsr. Pass initializer arguments after --.
Publishing
To npm the regular flow still works — npm publish, or deno pack to build
the tarball first. deno publish targets JSR only, from a deno.json with
name, version, and exports:
deno publish --dry-run
deno publish
Provenance attestation is automatic on GitHub Actions. deno bump-version patch
bumps a single package, or each versioned JSR package in workspace mode.
Guide: https://docs.deno.com/runtime/reference/cli/publish/
Reviewing Deno code
-Acommitted in a task where a scoped grant would work.deno.lockuncommitted, or CI runningdeno installinstead ofdeno ci.- Inline
jsr:/npm:specifiers in a project with apackage.json— usedeno addso the version lives in one place. Fine in standalone scripts. - A specifier with no version constraint.
- Dependencies or compiler options in
deno.jsonwhenpackage.jsonortsconfig.jsonexists. - Missing
deno fmt --check,deno lint,deno checkin CI.
Further reading
- https://docs.deno.com — runtime documentation
- https://docs.deno.com/api/ —
Deno.*API reference references/CLI.md— fuller subcommand and flag referencedeno <subcommand> --help— authoritative and version-accurate; check it before guessing at a flag.