deno

Deno

パッケージマネージャー、フォーマッター、リンター、テストランナー、型チェッカー、バンドラーを1つのバイナリにまとめた、JavaScript および TypeScript のランタイムです。TypeScript をそのまま実行できます。

Deno 2.9 以降が必要です。deno --version で確認し、deno upgrade で更新してください。

Deno は npm や bun と同じように動作します

Deno は、コードを移植するための別のエコシステムではありません。

• deno install は既存の package.json を読み取り、実際の node_modules を作成します。
• deno add express は npm からインストールします。プレフィックスのない名前は npm がデフォルトです。
• deno task build は package.json の scripts.build または deno.json の tasks.build を実行します。両方に定義されている場合は、deno.json が優先されます。
• Node の組み込みモジュールは、プレフィックスの有無にかかわらず動作します。node:fs と fs のどちらも解決されます。
• deno main.js でファイルを実行できます。deno run は省略可能です。
• Deno は tsconfig.json を読み取ります。

前提条件として、インポートを書き換えたり、JSR を採用したり、構成を変更したりするようユーザーに求めないでください。実質的な違いは、権限とnpm のライフサイクルスクリプトがデフォルトでは実行されないことの2つです。

単一ファイルのスクリプトには、ビルド手順も tsconfig.json も必要ありません。アプリケーションやフレームワークのプロジェクトは、通常のセットアップを維持してください。

既存のプロジェクトを移行するには、migrate-to-deno スキルを参照してください。

依存関係の管理

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 は CI コマンドであり、deno install ではありません。deno.lock が必要で、node_modules を削除し、ロックファイルに厳密に従ってインストールし、ロックファイルが古い場合は失敗します。--prod は devDependencies をスキップします。

dx は npx ／ bunx ／ pnpm dlx に相当し、deno x のエイリアスです。サンドボックスが無効な状態で実行されるため、npx と同じように注意して扱ってください。

Deno は、公開から1日未満のバージョンをインストールしません。これにより、侵害されたリリースがもたらすリスクを軽減できます。--min-dep-age で上書きできます。このオプションには、分（120）、ISO-8601 期間（P7D）、期限日、または無効にする場合の 0 を指定します。

deno add --min-dep-age=0 npm:some-package

ライフサイクルスクリプト（postinstall）はデフォルトでは実行されません。そのため、インストール後にネイティブアドオンが壊れているように見えることがよくあります。プロジェクトごとに一度、許可してください。

deno approve-scripts                              # interactive picker
deno install --allow-scripts=npm:better-sqlite3

設定ファイルの配置先

ファイル	内容
package.json	依存関係、スクリプト
tsconfig.json	TypeScript コンパイラーのオプション
deno.json	Deno の設定：fmt、lint、タスク、ワークスペース

依存関係は package.json に記述してください。他のすべてのツールがこれを読み取り、Deno もネイティブに解決できるためです。package.json がない場合に限り、依存関係を deno.json に記述してください。対象となるのは、単独のスクリプトや JSR パッケージです。同様に、deno.json の compilerOptions よりも tsconfig.json を優先してください。そうすれば、tsc とエディターで同じ設定が使われます。

deno.lock をコミットしてください。Deno は既存の package-lock.json、yarn.lock、bun.lock、または pnpm のロックファイルから内容を引き継いで作成し、固定されたバージョンを保持します。

node_modules のレイアウト

Deno は pnpm の分離レイアウトを使用します。実際のファイルは node_modules/.deno/ に置かれ、シンボリックリンクで公開されるため、パッケージは宣言していない依存関係をインポートできません。npm のフラットなホイスト済みツリーを必要とするツールには、次の設定を使用してください。

{ "nodeModulesLinker": "hoisted" }

nodeModulesDir は package.json がないプロジェクトにのみ適用されるため、適切な設定項目となることはほとんどありません。

Permissions

Deno は、許可を求めない限り、ファイルシステム、ネットワーク、環境変数、サブプロセスへのアクセスを許可しません。

deno run --allow-net=api.example.com --allow-read=./data main.ts
deno run -A main.ts          # allow everything

フラグ	短縮形	許可するもの
--allow-read[=paths]	-R	ファイルシステムの読み取り
--allow-write[=paths]	-W	ファイルシステムへの書き込み
--allow-net[=hosts]	-N	ネットワーク
--allow-env[=names]	-E	環境変数
--allow-sys[=apis]	-S	OS 情報
--allow-import[=hosts]	-I	リモートホストからのインポート
--allow-run[=bins]	—	サブプロセス
--allow-ffi[=paths]	—	ネイティブライブラリ（不安定）
--allow-all	-A	すべて

-S は --allow-sys であり、--allow-run ではありません。すべてのフラグには許可リストを指定できます。--allow-net=example.com:443 は、引数なしの --allow-net より優先されます。一致する --deny-* フラグは常に優先されます。

Requires net access to "..." と表示された場合は、そのアクセスに必要な権限を追加してください。信頼できるファーストパーティーのコードや移行中であれば -A を使ってもかまいませんが、タスクにコミットする際のデフォルトとしては適切ではありません。

Configuration

deno.json（または .jsonc）は、現在のディレクトリから上位へ向かって自動的に検出されます。

{
  "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/"]
}

トップレベルの exclude はすべてのサブコマンドに適用されます。ツールごとの exclude は対象をさらに絞り込みます。

deno.json では imports も設定できます。これは、名前だけの指定子を実際の指定先に対応付けるインポートマップです。package.json のないプロジェクトで依存関係を宣言する方法であり、JSR パッケージで name、version、exports とともに独自の依存関係を宣言する方法でもあります。

Workspaces

npm、Yarn、Bun のワークスペースはそのまま使えます。Deno は package.json の "workspaces" を直接読み取ります。例外は pnpm です。初回実行時に pnpm-workspace.yaml が deno.json に移行されるため、その後、再実行する必要があります。

{ "workspace": ["./packages/core", "./packages/cli"] }

メンバーは明示的に指定するか、単一階層の glob（"packages/*"）を指定します。** と否定はサポートされていません。deno task --filter '*' build を実行すると、メンバー全体に対してタスクを実行できます。

Packages: npm and JSR

npm を優先してください。エコシステムの中心であり、通常は deno add express を使います。標準ライブラリ（@std/*）には JSR を使用するか、ビルド手順なしで利用者が型を使える TypeScript を公開する場合に JSR を選びます。両者を併用しても問題ありません。

deno add jsr:@std/path npm:express
deno doc jsr:@std/path        # read a package's API from the terminal

Deno はかつて完全な URL インポート（https://deno.land/x/...）を使用していました。現在も動作しますが、推奨されていません。最新の方法にするには、deno add でパッケージを追加し、名前だけの指定子でインポートしてください。

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

これらは、設定や依存関係なしで prettier、eslint、jest/vitest、tsc、pkg/nexe を置き換えられますが、そのまま差し替えられるものではありません。互換性は完全ではないため、既存プロジェクトの移行には実作業が伴います。移行する必要はありません。 prettier、eslint、vitest をそのまま使い、Deno をランタイムおよびパッケージマネージャーとして利用してください。新しいプロジェクトでは組み込みツールを優先してください。

// deno-lint-ignore <rule>、// deno-lint-ignore-file、// deno-fmt-ignore、// deno-fmt-ignore-file で無効化できます。Markdown では、コードブロックの前に `` を記述すると、単独では有効なコードにならない説明用スニペットを保護できます。

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 はモジュールをホットリプレースし、それに失敗すると再起動します。これは deno run --watch-hmr のエイリアスです。

HTTP サーバーに依存関係は必要ありません。

Deno.serve((_req) => new Response("Hello"));

Starting a new project

ファイルを手作業で作成するのではなく、スキャフォールドを使ってください。

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 vite my-app       # scaffold from a package initializer

deno create は npm create／yarn create に相当し、そのエコシステムに対応しています（deno create astro など）。プレフィックスのない名前は npm を指し、--jsr を指定すると JSR が選択されます。

Publishing

npm への通常の公開フローは引き続き利用できます。npm publish を使うか、まず deno pack で tarball を作成してください。deno publish は JSR 専用であり、name、version、exports を含む deno.json から公開します。

deno publish --dry-run
deno publish

GitHub Actions ではプロベナンスの証明が自動的に行われます。ワークスペースのルートで deno bump-version patch を実行すると、すべてのメンバーのバージョンが更新されます。

ガイド：https://docs.deno.com/runtime/reference/cli/publish/

Deno コードのレビュー

• スコープを限定した許可で対応できるタスクで、-A をコミットしている。
• deno.lock が未コミットになっている、または CI で deno ci ではなく deno install を実行している。
• package.json があるプロジェクトで、jsr:／npm: の指定子をインラインで使っている。バージョンを一元管理できるよう、deno add を使用してください。スタンドアロンスクリプトでは問題ありません。
• バージョン制約のない指定子。
• package.json または tsconfig.json があるのに、deno.json に依存関係やコンパイラーオプションを指定している。
• CI に deno fmt --check、deno lint、deno check がない。

さらに詳しく

• https://docs.deno.com — ランタイムのドキュメント
• https://docs.deno.com/api/ — Deno.* API リファレンス
• references/CLI.md — サブコマンドとフラグの詳細なリファレンス
• deno <subcommand> --help — 公式かつバージョンに即した情報です。フラグを推測する前に確認してください。