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）の プロジェクト依存関係を、互換性のある最新バージョンに更新します。semver の範囲を尊重します。依存関係を最新の状態に保つために使用してください。
• deno upgrade - Deno ランタイム自体を最新バージョンに更新します。プロジェクトの依存関係とは関係ありません。

deno update の実行後は、必ず API の破壊的変更を確認してください。特に、semver の範囲によって破壊的変更を含む更新が取得される可能性のあるアルファ版／プレリリースのパッケージに注意してください。

CI/CD

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

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

設定

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

{
  "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	コードを 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 を実行し忘れる

コミットする前に、必ずフォーマットと 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 は「Requires net access」エラーを表示します。コードに必要な権限を個別に必ず付与してください。

依存関係に deno add を使用しない

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

deno add を使用すると、ロックファイルを同期した状態に保てます。インポートを手動で編集して deno.json を更新しなくても動作しますが、ロックファイルによるメリットが得られません。