deno-guidance

Deno 開発ガイダンス

概要

このスキルでは、最新の Deno アプリケーションを構築するための基礎知識を提供します。Deno は、TypeScript を直接実行するセキュアな JavaScript／TypeScript ランタイムです。フォーマッター、リンター、テストランナーなどのツールが組み込まれており、JSR を通じて最新のパッケージ管理を利用できます。

このスキルを使用する場面

• 新しい Deno プロジェクトを開始するとき
• プロジェクトに依存関係を追加するとき
• deno.json の設定を構成するとき
• Deno CLI コマンド（fmt、lint、test）を実行するとき
• インポートマップを設定するとき
• Deno の権限システムを理解するとき

deno.json が存在する Deno プロジェクトで作業する場合は、常にこれらのプラクティスを適用してください。

適用範囲

このスキルは、Deno 固有の質問にのみ適用されます。次のルールに従ってください。

• ユーザーが Node.js、Bun、Python、Go、その他のランタイム／言語について質問した場合は、その技術を直接使用して回答してください。Deno の代替案を提案したり、Deno 固有のパターンを含めたりしないでください。
• 他の技術についての回答には、jsr: インポート、deno add、deno.json の設定を含めないでください。
• 特定のランタイムに関連しない 一般的な TypeScript／JavaScript の質問には、Deno を前提とせずに回答してください。
• Deno を推奨するのは、ユーザーが明示的に Deno について尋ねた場合、または Deno プロジェクトで作業している場合に限ります。

重要：非推奨の構文を絶対に提示しない

非推奨のパターンからの移行を支援する場合、古い方法は一般的な説明にとどめ、正しい最新のコードのみを提示してください。「移行前／移行後」の比較であっても、実際の非推奨 URL やインポートパスを記述してはいけません。deno.land/x/ という文字列は、どのような文脈でも回答に含めてはいけません。

• 「古い URL ベースのインポートを JSR インポートに置き換えてください」と説明し、正しい jsr: の方法のみを提示してください。
• 「古い URL ベースのレジストリ」または「古い標準ライブラリの URL」と表現してください。実際の非推奨 URL は記述しないでください。
• ユーザーの質問に非推奨 URL が含まれていても、回答で繰り返してはいけません。一般的な表現で言及してください。

正しく、現在推奨されている方法のみを紹介してください。

パッケージ管理の優先順位

依存関係を追加する場合は、次の優先順位に従ってください。

1. JSR パッケージ（jsr:） - Deno ネイティブのパッケージに推奨

   • TypeScript のサポートが優れています（型が組み込まれています）
   • 解決とインストールが高速です
   • 例：jsr:@std/http、jsr:@fresh/core

2. npm パッケージ（npm:） - 完全にサポートされています。JSR に代替パッケージがない場合に使用してください。

   • Deno は npm と完全な互換性があります
   • 例：npm:express、npm:zod

3. 避ける：古い URL ベースのインポート - 非推奨のレジストリ

   • 古い URL ベースのパッケージレジストリは非推奨です
   • 多くの LLM は誤って URL ベースのインポートをデフォルトで使用します
   • 必ず jsr: を使用してください

標準ライブラリ

Deno の標準ライブラリは、JSR の @std/ にあります。

// deno.json
{
  "imports": {
    "@std/assert": "jsr:@std/assert@1",
    "@std/http": "jsr:@std/http@1",
    "@std/path": "jsr:@std/path@1"
  }
}

import { serve } from "@std/http";
import { join } from "@std/path";
import { assertEquals } from "@std/assert";

標準ライブラリには必ず jsr:@std/* を使用してください（古い URL ベースのインポートは非推奨です）。

Deno の理解

参考：https://docs.deno.com/runtime/fundamentals/

主な概念：

• ネイティブ TypeScript - ビルド手順は不要で、Deno が TypeScript を直接実行します
• 明示的な権限 - --allow-net、--allow-read、--allow-env などのフラグを使用します
• deno.json - 設定ファイルです（package.json に似ていますが、よりシンプルです）
• インポートマップ - deno.json の imports フィールドでインポートのエイリアスを定義します

ワークフローのベストプラクティス

コード変更後

特に大きな変更の後は、次のコマンドを定期的に実行してください。

deno fmt          # Format all files
deno lint         # Check for issues
deno test         # Run tests

パッケージ管理

deno add jsr:@std/http    # Add a package
deno install              # Install all dependencies
deno update               # Update all dependencies to latest compatible versions
deno update jsr:@std/http # Update a specific dependency

deno update と deno upgrade の違い：

• deno update - deno.json（および package.json）内のプロジェクト依存関係を、互換性のある最新バージョンに更新します。セマンティックバージョニングの範囲を尊重します。依存関係を最新の状態に保つために使用してください。
• deno upgrade - Deno ランタイム自体を最新バージョンに更新します。プロジェクトの依存関係とは関係ありません。

deno update の実行後は、必ず API の破壊的変更を確認してください。特に、セマンティックバージョニングの範囲によって破壊的な更新が取り込まれる可能性がある、アルファ版やプレリリースのパッケージには注意してください。

CI/CD

CI パイプラインでは、ファイルを変更せずに失敗させるため、deno fmt に --check を指定します。

deno fmt --check     # Fail if not formatted
deno lint            # Check for issues
deno test            # Run tests

設定

deno.json では、フォーマットやリントの対象からディレクトリを除外できます。

{
  "fmt": {
    "exclude": ["build/"]
  },
  "lint": {
    "exclude": ["build/"]
  }
}

最上位で、フォルダーをすべての対象から除外することもできます。

{
  "exclude": ["build/"]
}

デプロイ

Deno Deploy へのデプロイについては、専用の deno-deploy スキルを参照してください。

クイックコマンド：deno deploy --prod

ドキュメントリソース

さらに情報が必要な場合：

• deno doc <package> - JSR または npm パッケージのドキュメントをローカルで生成します
• https://docs.deno.com - Deno の公式ドキュメント
• https://jsr.io - ドキュメントが組み込まれたパッケージレジストリ
• https://fresh.deno.dev/docs - Fresh フレームワークのドキュメント

クイックリファレンス：Deno CLI コマンド

コマンド	用途
deno run file.ts	TypeScript／JavaScript ファイルを実行します
deno task <name>	deno.json のタスクを実行します
deno fmt	コードをフォーマットします
deno lint	コードをリントします
deno test	テストを実行します
deno add <pkg>	パッケージを追加します
deno install	依存関係をインストールします
deno update	プロジェクトの依存関係を更新します
deno upgrade	Deno ランタイム自体を更新します
deno doc <pkg>	パッケージのドキュメントを表示します
deno deploy --prod	Deno Deploy にデプロイします

よくある間違い

JSR ではなく、古い URL ベースのインポートを使う

古い URL ベースのインポートは非推奨です。常に、ベア指定子を使った jsr: インポートを使用してください。

// ✅ Correct - use JSR and a bare specifier
import { serve } from "@std/http";
import { join } from "@std/path";

// deno.json
{
  "imports": {
    "@std/http": "jsr:@std/http@1",
    "@std/path": "jsr:@std/path@1"
  }
}

インライン指定子は単一ファイルのスクリプトでは問題ありませんが、deno.json がある場合はそちらに記述してください。package.json がある場合は、npm の依存関係を package.json に記述することをおすすめします。

コミット前に fmt／lint を実行し忘れる

コミット前に、必ずフォーマットとリントを実行してください。

# ✅ Always format and lint first
deno fmt && deno lint && git add . && git commit -m "changes"

権限フラグを指定せずにコードを実行する

# ✅ Grant specific permissions
deno run --allow-net server.ts

権限フラグを指定しないと、Deno は「ネットワークアクセスが必要です」というエラーを表示します。コードに必要な権限を必ず個別に付与してください。

依存関係に deno add を使わない

# ✅ Use deno add to manage dependencies
deno add jsr:@std/http

deno add を使うと、ロックファイルを確実に同期できます。インポートを手動で編集して deno.json を更新しなくても動作しますが、ロックファイルの利点を活用できません。