orpc-contract-firstスキルでDifyのAPI開発を型安全に進める方法

フロントエンドとバックエンドの間でAPI仕様がずれると、実行時エラーの原因になります。Contract-Firstアプローチを使えば、型定義を起点にした安全なAPI開発が可能です。

この記事では、Difyリポジトリのorpc-contract-firstスキルを使って、oRPCパターンによる型安全なAPIレイヤーを構築する方法を解説します。

このスキルは何をしてくれるのか

orpc-contract-firstは、Difyフロントエンドでcontract-firstパターンを使った型安全なAPI実装をガイドするスキルです：

• oRPCコントラクトの定義（path、method、input、output）
• ルーターへの登録とAPIプレフィックスによるグループ化
• TanStack Queryとの統合によるカスタムフック生成
• 型の自動推論（InferContractRouterInputs等）

Difyフロントエンドの開発に携わり、API連携の型安全性を確保したい開発者に向いています。

インストール方法

前提条件

• Claude Codeがインストール済みであること
• Difyプロジェクトのソースコードへのアクセス

インストールコマンド

Copyclaude mcp add github.com/langgenius/dify/tree/main/.claude/skills/orpc-contract-first

使い方

コントラクトの定義

web/contract/console/{domain}.tsにコントラクトを作成します：

Copyimport { oc } from '@orpc/contract'

export const systemContract = {
  getInfo: oc.route({ path: '/info', method: 'GET' }),
  updateSettings: oc.route({
    path: '/settings',
    method: 'POST',
    body: settingsSchema,
  }),
}

ルーターへの登録

web/contract/router.tsでAPIプレフィックスに沿ってネストします：

Copyexport const consoleRouterContract = {
  system: systemContract,
  billing: billingContract,
}

カスタムフックの作成

web/service/use-{domain}.tsにTanStack Query連携のフックを作成します。クエリキーはconsoleQuery.{group}.{contract}.queryKey()で自動生成されます。

input構造のルール

inputは常に{ params, query?, body? }形式で定義します。パスパラメータは{paramName}形式で指定します。

知っておくべき注意点

barrel fileを使わない

Difyの規約として、barrel file（index.tsからのre-export）は避け、各ファイルから直接インポートします。

oRPCとTypeScriptの知識が前提

このスキルはoRPCとTypeScriptの型システムに関する基本知識を前提としています。初めてoRPCに触れる場合は、公式ドキュメントの確認を推奨します。

Difyプロジェクト固有のパターン

ルーターのネスト方法やクエリキーの命名規則はDifyプロジェクト固有のパターンです。他のプロジェクトにそのまま適用することは想定されていません。

まとめ

orpc-contract-firstスキルを使うと、Difyフロントエンドのcontract-firstなAPI開発を、コントラクト定義→ルーター登録→フック生成の流れで型安全に進められます。APIの型定義を起点にすることで、フロントエンドとバックエンドの不整合を防げます。

関連リンク

→ orpc-contract-first スキル詳細