Deno
目的
モダンなDenoプロジェクト、特にコードベースがDenoとNode指向のツールを混在させる場合、古いDenoパターンからのクリーンな移行パスが必要な場合、または既存のTypeScript/NodeリポジトリにDenoを採用する場合に、移植性の高いデフォルト設定を提供します。
このスキルを使用すべき場合
- Denoスクリプト、サーバー、エッジコードを作成する場合。
deno.json、タスク、依存関係ソースを設定する場合。- 既存の
tsconfig.jsonやeslint.config.*ファイルをDenoと共存させるように適応させる場合。 - 単一リポジトリ内でDenoコードとNodeまたはTypeScriptコードを混在させる場合。
- Denoのパーミッション、テスト、ランタイムパターンをレビューする場合。
デフォルト設定
- Denoの信頼できる情報源として
deno.jsonを使用します。 - Denoがワークフローを所有する場合、アドホックなラッパーよりも
deno check、deno task、deno fmt、deno lint、deno testを優先します。 - Denoが所有するコードにはDenoネイティブツールで十分です。リポジトリにDeno境界外のNode管理パッケージやスクリプトもある場合にのみYarnを使用します。
tsconfig.jsonは、Nodeが所有するパスのため、またはDenoワークスペースとディレクトリスコープではクリーンに表現できないTypeScriptプロジェクトグラフケースのためだけに保持します。- モダンなNodeも組み込みの型ストリッピングを通じてTypeScriptを直接実行できることを覚えておいてください。
tscやts-nodeを避けるためだけではなく、そのランタイム、パーミッション、依存関係、ツールモデルのためにDenoを選択してください。 - Denoが所有するファイルには
deno lintとdeno fmtを優先します。リポジトリやエディタが本当にESLintエコシステムを必要とする場合にのみESLintを追加します。 - ESLintを
deno lintに置き換える場合、既存のESLintの意図を検査し、設定を丸ごと破棄するのではなく、deno.jsonのincludes、excludes、lintルール、または文書化された例外に引き継ぎます。 tscをdeno checkに置き換える場合、既存のtsconfig.jsonを検査し、関連するコンパイラオプション、includes、excludes、libs、および厳格さの期待値をdeno.jsonまたは明確にスコープされた保持するtsconfig.jsonに変換します。- ESLintなどのnpmベースのエディタツールをDenoリポジトリ内で実行する必要がある場合、
nodeModulesDir: "auto"を設定し、コマンドをdeno taskでラップします。 - Denoが依存関係管理を所有する場合、
deno run npm:<package>をインストールの代わりとして扱わず、deno addで依存関係をインストールします。開発専用のCLIやツールにはdeno add --dev npm:<package>を使用します。 - インストールされたCLIツールについては、ツールにちなんだ名前の
deno taskを作成し、インストールされたバイナリを名前で呼び出します。例えば、deno add --dev npm:sample-toolの後に、"sample-tool": "sample-tool"を追加します。 - Denoが所有するコードではデフォルトで
.tsモジュールを優先します。Denoが不要とするビルドステップを避けるためだけにJavaScriptにダウングレードしないでください。 - 散在するレガシーURLインポートよりも、JSRパッケージ、
npm:指定子、または明示的なインポートマップエントリを優先します。 - npmベースのCLIに1回限りの実行とうまく連携しないインストールまたはポストインストール動作がある場合、
nodeModulesDir: "auto"を設定し、allowScriptsでパッケージを許可し、deno addまたはdeno add --devで依存関係を追加し、deno taskからインストールされたバイナリを呼び出します。 - Deno 2は
package.json、npmパッケージ、Node組み込みモジュールと意図的に互換性があります。両方の世界をtsconfig.jsonに詰め込もうとするのではなく、Deno固有の設定はdeno.jsonに保持します。 - サーバーにはWeb標準APIと
Deno.serveを優先します。 - パーミッションを後付けではなく設計上の決定として扱います。
タスクフレーミング
| コマンドまたはアクション | 内容 | 理由 | タイミング | 期待される結果 |
|---|---|---|---|---|
tsconfig.jsonとESLintを慎重に採用 | Node所有の設定に残すものとdeno.jsonに移動するものを決定する。 | 両方のツールチェーンが同じファイルを所有しようとすると、ハイブリッドリポジトリはすぐに煩雑になる。 | 既存のTypeScriptまたはNodeコードベースにDenoを導入するとき。 | DenoとNodeのツールがそれぞれ明示的な所有権境界を持つ。 |
deno.jsonを設定 | Denoの設定ファイルでタスク、コンパイラオプション、依存関係の規則を定義する。 | DenoはNode中心の設定を偶然借用するのではなく、独自のワークフローを所有すべきである。 | Denoプロジェクトを開始または再構築するとき。 | Denoコマンドとエディタの動作が一貫する。 |
| Deno所有のnpm CLIをインストール | 開発ツールに対してdeno add --dev npm:<package>を実行し、インストールされたバイナリを呼び出す同名のタスクを追加する。 | 依存関係、ロックファイル、ローカルバイナリ、タスクエントリポイントがDenoのパッケージマネージャの下で整合する。 | Deno所有のワークフローにコードジェネレータ、ブラウザ自動化CLI、リンター、フォーマッタなどのツールを追加するとき。 | deno.jsonとロックファイルが依存関係を記録し、deno task <tool>がインストールされたCLIを実行する。 |
| ハイブリッド境界を設定 | 混合リポジトリでDeno所有のパスとNode所有のパスを分離する。 | ツールの競合はハイブリッドリポジトリの最も一般的な障害の1つである。 | DenoコードがNodeまたはTSツールの隣に存在するとき。 | エディタとコマンドが同じファイルを巡って競合しない。 |
| パーミッションをレビュー | ランタイムアクセスに明示的なパーミッションとタスクラッパーを選択する。 | Denoのセキュリティモデルは、パーミッションが意図的に設定されている場合にのみ役立つ。 | 新しいスクリプトを実行する前、またはDeno CLIワークフローを公開する前。 | ファイルシステム、ネットワーク、環境へのアクセスが意図的かつ監査可能である。 |
| Denoワークフローのトラブルシューティング | 推測する前にDenoネイティブのチェック、デバッガフラグ、モジュールグラフツールを使用する。 | 多くのDenoの問題はコードのバグではなく、設定、パーミッション、所有権の問題である。 | ハイブリッドリポジトリまたは移行したツールチェーンが予期せぬ動作をするとき。 | 根本原因が設定、パーミッション、またはランタイム動作に絞り込まれる。 |
コアルール
TypeScript、tsconfig.json、ライブラリ
- Denoコンパイラ設定は
deno.jsonのcompilerOptionsに配置します。deno checkを実行するためだけに完全なNodeのtsconfig.jsonをコピーしないでください。 - 既存のNode + TypeScriptワークスペースは
tsconfig.jsonを保持できます。Denoはディレクトリにdeno.jsonまたはpackage.jsonも含まれている場合、それを調査します。 - 親の
deno.jsonがcompilerOptionsを定義している場合、それらは重複するtsconfig.jsonオプションよりも優先されます。 - 目標が
tscの置き換えである場合、まず現在のtsconfig.jsonの動作を棚卸しします。意味のある厳格さ、モジュール解決、JSX、ライブラリ、include、excludeの決定をDeno設定に保持するか、なぜそれらがもはや適用されないかを文書化します。 deno.jsonのcompilerOptions.libを使用して、実際のランタイムサーフェスをモデル化します。SSRまたはブラウザ + Denoコードの場合は、["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]のような組み合わせを優先します。Denoワーカーの場合は、["deno.worker"]を優先します。- JavaScriptモジュールが明示的な型チェックまたは宣言を必要とする場合、
compilerOptions.checkJs、// @ts-check、@ts-types、@ts-self-types、またはcompilerOptions.typesを使用します。 tsconfig.jsonは、Nodeが所有するフォルダ、TSプロジェクト参照、またはinclude/excludeの粒度が依然としてそれを必要とする場合にのみ保持します。
リンティング、フォーマット、ESLint
- Denoが所有するコードのデフォルトのリント所有者として、
deno lintとdeno.jsonのlintセクションを使用します。 - Denoが所有するコードのデフォルトのフォーマッタとして、
deno fmtとdeno.jsonのfmtセクションを使用します。 deno lintはすでにESLintに触発された推奨ルールセットをカバーしています。習慣だけでESLintを保持しないでください。- 目標がESLintの置き換えである場合、まず現在の
eslint.config.*の動作を棚卸しします。意味のあるファイルスコープ、グローバル、無視、ルールの意図をDeno lint/fmt設定に保持するか、Denoがすでにカバーまたは拒否しているため意図的に削除されたルールを文書化します。 - カスタムのDeno専用ルールが必要な場合、
lint.pluginsを検討します。lintプラグインAPIは実験的であり、Deno 2.2以降が必要です。 - リポジトリまたはエディタが依然としてESLintを必要とする場合、それを明示的なセカンダリツールにします。
nodeModulesDir: "auto"を設定し、eslint.config.jsを作成し、呼び出しをdeno taskでラップします(例:deno task eslint)。 - 可能な限り、ファイルセットごとに1つのリント所有者を維持します。
deno lintとESLintの両方が同じファイルで実行される場合、その理由を文書化するか、重複した矛盾する診断を期待します。
Node互換性とハイブリッドリポジトリ
- Deno 2は
package.json、node_modules、npmワークスペース、Node組み込みモジュールを理解します。ハイブリッドリポジトリは回避策ではなく、サポートされるパスです。 - モダンなNodeもTypeScriptを直接実行できます。ハイブリッドリポジトリでは、TypeScriptの実行だけではなく、パーミッション、依存関係モデル、タスクランナー、デプロイターゲットによってNodeとDenoの所有権を決定します。
package.jsonが存在し、Denoにnode_modulesを自動作成および更新させたい場合、nodeModulesDir: "auto"を設定します。package.jsonがある場合、Deno 2はデフォルトで"manual"になります。nodeModulesDirはワークスペースルートの設定です。ワークスペースメンバーごとに設定しようとしないでください。- Denoが依存関係更新フローを所有する場合、
deno installまたはdeno addを使用します。Deno 1の自動インストール動作を想定しないでください。 - Deno所有リポジトリの開発専用npm CLIには
deno add --dev npm:<package>を使用します。追加後、"sample-tool": "deno run -A npm:sample-tool"ではなく、"sample-tool": "sample-tool"のようなdeno taskを通じてバイナリを公開します。 deno addによって生成されたマニフェストとロックファイルの更新をチェックインします。タスクエイリアスだけでは依存関係のインストールにはなりません。- 混合ワークスペース全体に対してDenoツールを有効にしないでください。ただし、1つのサブツリーのみがDenoである場合を除きます。
- NodeとDenoのツールが同じファイルを巡って競合しないように、
deno.enablePathsなどのパスベースのエディタアクティベーションを優先します。 - Denoの境界をフォルダ構造、タスク、ドキュメントで明示的に保ちます。
パーミッション、環境、セキュリティ
-Aよりも、狭い--allow-*フラグまたはdeno.jsonの名前付きパーミッションセットを優先します。- リポジトリが
deno.jsonでパーミッションセットを定義している場合、-Pまたは--permission-set=<name>を使用します。 - CLIが
.envファイルをロードする必要がある場合は--env-fileを、プログラム自体がロードする必要がある場合は@std/dotenvを使用します。どちらも明示的な環境とファイルパーミッションが必要です。 - アプリケーションコードには最小権限を優先し、タスクと例で環境、ファイルシステム、ネットワーク、サブプロセスへのアクセスをわかりやすくします。
--allow-runと--allow-ffiをサンドボックスエスケープハッチとして扱います。完全な信頼が明示的に意図されている場合を除き、--allow-run=denoを避けてください。- パーミッションのデバッグまたは監査には、
DENO_TRACE_PERMISSIONS=1とDENO_AUDIT_PERMISSIONS=<path>を使用します。
トラブルシューティングと移行
- ランタイムの成功と型チェックの動作が乖離する場合、
deno check、deno check --all、またはdeno run --checkを使用します。 - モジュールグラフを検査し、インポート、キャッシュ、パーミッションの動作を理解するために
deno info <entrypoint>を使用します。 - すべてのリント問題を手動で編集する前に、一般的な移行クリーンアップのために
deno lint --fixを使用します。 - デバッガのセットアップには、プロセスが短命の場合は
--inspect-brkを、インスペクタまたはモジュール解決が混乱する場合は--log-level=debugを、ランタイムがハングするか異常に遅い場合は--strace-opsを使用します。 - トラブルシューティングの質問が実際にはパフォーマンスに関するものである場合、
--cpu-prof、--cpu-prof-md、--cpu-prof-flamegraphなどのCPUプロファイリングフラグを使用します。 - 移行アドバイスはDeno 2のデフォルトを反映する必要があります。
nodeModulesDirは"none" | "auto" | "manual"を使用し、deno cacheはdeno install --entrypointになり、deno vendorは"vendor": trueになり、Deno.run()はnew Deno.Command()になるべきであり、Deno.serveHttp()はDeno.serve()になるべきです。 - 非推非推奨のインポートアサーションの代わりに、
with { type: "json" }などのインポート属性を使用します。
落とし穴
- DenoとNodeのツールが同じファイルを主張する場合、エディタの診断がノイズが多く誤解を招くものになります。
package.jsonが存在する場合、Deno 2はnodeModulesDirを"manual"にデフォルト設定します。これを忘れることは、npmベースのツールが半分しかインストールされていないように見える一般的な理由です。- VS Code ESLint拡張機能がワークフローの一部である場合、Denoのグローバルキャッシュだけからパッケージを解決しません。ローカルの
node_modulesディレクトリが必要です。 deno runはデフォルトで型チェックをスキップするため、実行が成功してもdeno checkが成功するという証拠にはなりません。deno run npm:<package>にシェルアウトするdeno taskは1回限りの実行ショートカットであり、適切な依存関係のインストールではありません。Deno所有のリポジトリで「このCLIをインストールしてセットアップする」という質問へのデフォルトの答えとして使用しないでください。-Aは信頼されたツールには許容されますが、通常のアプリケーションコードには間違ったデフォルトです。- 実際の混合ランタイムリポジトリでのSupabaseを含む一部のnpm CLIは、
deno run npm:...よりもnode_modulesの下にインストールされたバイナリを介した方が信頼性の低いインストール時動作に依存しています。 - 古いURLインポートとワークスペース全体のアクティベーションパターンは移行の補助であり、現代のデフォルトではありません。
検証
deno.jsonがDenoの設定とタスクを所有していること。- 保持されている
tsconfig.jsonまたはESLintの所有権が明示的であり、適切なファイルにスコープされていること。 - ESLintまたは
tscの置き換えが既存の設定からの有用な動作を保持するか、意図的に削除された理由を文書化していること。 - ハイブリッドリポジトリのDenoとNodeの部分がツールを巡って競合しないこと。
- 依存関係指定子がモダンで明示的であること。
- Deno所有のnpm CLIが
deno addまたはdeno add --devで追加され、マニフェストとロックファイルに記録され、インストールされたバイナリ名を呼び出すタスクを通じて実行されること。 nodeModulesDir、エディタアクティベーション、およびnpmベースのDenoツールが意図的に設定されていること。- npm CLIがDenoタスクから駆動される場合、リポジトリが偶発的なインストール副作用に依存するのではなく、
nodeModulesDirとallowScriptsを意図的に設定していること。 - パーミッションが意図的であり、重要事項について文書化されていること。
- トラブルシューティングガイダンスが、一般的なNodeまたはTypeScriptのデバッグアドバイスに頼る前に、Denoネイティブのチェックから始まること。
参考資料
tsconfig.json、ESLint、ハイブリッドDeno/Node移行、またはDeno境界のトラブルシューティングに関するタスクについては、./references/adoption-playbook.mdを読んでください。- Deno LLMサマリー: https://docs.deno.com/llms-summary.txt
- Deno設定リファレンス: https://docs.deno.com/runtime/fundamentals/configuration/
- Deno TypeScript設定リファレンス: https://docs.deno.com/runtime/reference/ts_config_migration/
- Denoセキュリティリファレンス: https://docs.deno.com/runtime/fundamentals/security/
./references/che…を読んでください。