migrate-to-deno

Deno への移行

Deno 2.9 以降が必要です。移行後の Deno の一般的な使い方については、deno スキルを参照してください。

ほとんどの Node プロジェクトはすでに Deno で動作します

Deno は既存の package.json を読み込み、同じ npm パッケージを解決して、 実際の node_modules を作成し、同じスクリプトを実行し、node: 組み込み機能を サポートします。TypeScript はビルド手順なしで実行できます。

通常、変更するコードはありません。変わるのは、どのバイナリを実行するかだけです。 まず import を jsr: に書き換えたり、依存関係を Deno 専用のものに置き換えたり、 ディレクトリ構成を変更したりしないでください。それを提案するのが、移行が失敗する 最も一般的な原因です。

段階を踏んで移行する

各段階はそれぞれ単独で役立ち、元に戻すこともできます。プロジェクトに合ったところで 止めてください。段階 1 で止めるチームも多くあります。

段階 1 — パッケージマネージャーとしてのみ Deno を使う

deno install

package.json を読み込み、同じ依存関係を解決して node_modules を作成し、 deno.lock を生成します。既存の package-lock.json、yarn.lock、bun.lock、 または pnpm のロックファイルがあれば、そこから内容を引き継ぐため、固定バージョンと 整合性ハッシュが変わらず維持されます。

アプリは引き続き node で実行されるため、チームメイトへの影響はありません。 確認が済んだら deno.lock をコミットしてください。元に戻すには： deno.lock と node_modules を削除してから、npm install を実行します。

段階 2 — Deno で実行する

deno run -A main.js      # or: deno -A main.js
deno task build          # runs scripts.build from package.json

ここでは -A を使ってください。目的はプログラムが動作することを確認することであり、 権限ポリシーを設計することではありません。両方を同時に変更すると、失敗の原因が 分かりにくくなります。

段階 3 — 権限を厳密にする

-A を、動作する最小限の権限セットに置き換えます。実行して、要求されたものを確認し、 必要なものだけを許可してください。

deno run --allow-net=api.example.com --allow-read=./config --allow-env=PORT main.js

これにより Node では得られない利点が得られ、デプロイ前に対応する価値があります。

段階 4 — 組み込みツールチェーンを任意で採用する

prettier の代わりに deno fmt、eslint の代わりに deno lint、jest や vitest の代わりに deno test、tsc の代わりに deno check、nodemon の代わりに deno watch、pkg の 代わりに deno compile を使います。

任意ですが、既存のプロジェクトでは通常、移行する価値はありません。 これらは そのまま置き換えられるものではなく、互換性も完全ではないため、設定変更ではなく、 本格的な移行になります。prettier、eslint、vitest に満足しているプロジェクトは、 それらを使い続け、Deno はランタイムとパッケージマネージャーとしてのみ使うのが よいでしょう。新しいプロジェクトでは組み込みツールを優先してください。既存の プロジェクトを移行する場合は、ツールを一つずつ切り替えてください。

コマンドの対応表

タスク	npm	Yarn	pnpm	Bun	Deno
すべてをインストール	npm install	yarn install	pnpm install	bun install	deno install
追加	npm i <p>	yarn add <p>	pnpm add <p>	bun add <p>	deno add <p>
開発用に追加	npm i -D <p>	yarn add -D <p>	pnpm add -D <p>	bun add -d <p>	deno add -D <p>
削除	npm uninstall <p>	yarn remove <p>	pnpm remove <p>	bun remove <p>	deno remove <p>
CI 用インストール	npm ci	yarn install --immutable†	pnpm i --frozen-lockfile	bun install --frozen-lockfile	deno ci
スクリプトを実行	npm run <s>	yarn <s>	pnpm <s>	bun run <s>	deno task <s>
バイナリを実行	npx <p>	yarn dlx <p>	pnpm dlx <p>	bunx <p>	dx <p>
古いバージョンを確認	npm outdated	yarn outdated‡	pnpm outdated	bun outdated	deno outdated
監査	npm audit	yarn npm audit†	pnpm audit	bun audit	deno audit
依存理由を確認	npm ls <p>	yarn why <p>	pnpm why <p>	bun why <p>	deno why <p>
ファイルを実行	node f.js			bun f.ts	deno f.ts
TS を実行	ts-node f.ts			bun f.ts	deno f.ts
監視	nodemon f.js			bun --watch f.ts	deno watch f.ts
フォーマット	prettier			prettier	deno fmt
リント	eslint				deno lint
テスト	jest, vitest			bun test	deno test
カバレッジ	nyc, c8				deno coverage
型チェック	tsc --noEmit			tsc	deno check
バイナリをバンドル	pkg, nexe			bun build --compile	deno compile

† Yarn Berry（v2 以降）の表記です。Yarn Classic（v1）では yarn install --frozen-lockfile と yarn audit を使用します。

‡ Yarn Classic のみです。Berry では yarn outdated が削除されています。

dx は Deno と一緒にインストールされる別個のバイナリで、deno x のエイリアスです。 トップレベルの deno --help の出力には表示されません。npx と同様に、サンドボックスを無効にしてパッケージを実行します。

実際に問題を起こす4つのこと

Requires net access to "..."（または read、env、run）

Deno はデフォルトでは何も許可しません。該当する権限を追加するか、プログラムが正常に動作することをまず確認する間は -A を指定してください。

ReferenceError: require is not defined

CommonJS を含むファイルが ESM として解析されています。.cjs は常に CommonJS、.mjs は常に ESM です。.js と .ts は、最も近い package.json の "type" に従います。CommonJS プロジェクトの場合は、"type": "commonjs" を設定してください。

依存関係が壊れている、または postinstall が実行されなかった

ライフサイクルスクリプトはデフォルトでは実行されません。ネイティブアドオンはすぐに影響を受けます。承認は設定ファイルに記録されるため、一度だけ実行すれば十分です。

deno approve-scripts                              # interactive picker
deno install --allow-scripts=npm:better-sqlite3   # or name them directly

ツールが node_modules 内のファイルを見つけられない

Deno のレイアウトは pnpm 方式です。実際のファイルは node_modules/.deno/ にあり、シンボリックリンクを介して公開されます。npm のフラットなホイスト済みツリーを前提とするツールには、次の設定が必要です。

{ "nodeModulesLinker": "hoisted" }

Deno に相当するものがない機能

回避策を無理に考案しても長続きしない場合は、相当するものがないと伝えてください。

• Yarn Plug'n'Play。 Deno は実際の node_modules を作成します。.pnp.cjs は使用されず、.yarnrc.yml のリゾルバー設定も引き継がれません。
• yarn patch／pnpm のパッチ適用済み依存関係。 ベンダー化するか、フォークしてください。
• overrides／resolutions。 代わりに、インポートマップのエントリーでバージョンを固定してください。
• .npmrc／.yarnrc.yml でのレジストリとリゾルバーの調整。
• Bun のビルド機能 — マクロ、HTMLRewriter、HTML エントリーポイント。

ツールごとの詳細

• references/FROM_NPM.md — ロックファイルのシード、node_modules のレイアウト、オーバーライド
• references/FROM_YARN.md — Plug'n'Play、Berry と Classic、ワークスペース
• references/FROM_PNPM.md — pnpm-workspace.yaml、catalog:、パッチ
• references/FROM_BUN.md — Bun API の翻訳、bunfig.toml
• references/NODE_APIS.md — node: 組み込みモジュール、DENO_COMPAT、CJS／ESM

関連資料

• https://docs.deno.com/runtime/migrate/ — 公式の移行ガイド
• https://docs.deno.com/runtime/fundamentals/node/ — Node と npm の互換性
• https://docs.deno.com/runtime/reference/node_apis/ — モジュールごとの Node API の対応状況