メインコンテンツまでスキップ

IPCルートの追加

このガイドでは、仮想の「お気に入り」機能を例として、型定義からフロントエンドのHookまで、IPCルート開発の完全なフローを説明します。

通信アーキテクチャの概要​

Renderer Process (React)
    | window.api.favorites.list()
    v
Preload Script (contextBridge)
    | ipcRenderer.invoke('favorites:list', authToken)
    v
Main Process Router (BaseRouter.secureHandle)
    | auth validation → param validation (Zod)
    v
Main Process Service
    | business logic → database operations
    v
Return result → Preload → Renderer

すべてのIPC呼び出しには自動的に authToken が付与され、secureHandle が一元的に検証します。認証を手動で処理する必要はありません。

ステップ1: 共有型の定義​

ファイル: packages/desktop/app/shared/contracts/favorites-types.ts

export interface Favorite {
  id: string;
  sessionId: string;
  messageId: string;
  note?: string;
  createdAt: string;
}

export interface CreateFavoriteInput {
  sessionId: string;
  messageId: string;
  note?: string;
}

export interface UpdateFavoriteInput {
  note?: string;
}

共有型は @shared/contracts/ 以下に配置します。フロントエンドとバックエンドの両方が @shared/contracts/favorites-types 経由でインポートでき、境界をまたいで型の一貫性が保たれます。

ステップ2: バックエンドサービスの作成​

ファイル: packages/desktop/app/main/services/content/favorites/FavoritesService.ts

import type { DbRpc } from '../../workers/types';
import type {
  CreateFavoriteInput,
  Favorite,
  UpdateFavoriteInput,
} from '@shared/contracts/favorites-types';

export class FavoritesService {
  constructor(private readonly db: DbRpc) {}

  async list(sessionId?: string): Promise<Favorite[]> {
    return this.db.favorites_list({ sessionId });
  }

  async create(input: CreateFavoriteInput): Promise<Favorite> {
    return this.db.favorites_create(input);
  }

  async update(id: string, input: UpdateFavoriteInput): Promise<Favorite> {
    return this.db.favorites_update({ id, ...input });
  }

  async delete(id: string): Promise<void> {
    return this.db.favorites_delete({ id });
  }
}

:::warning 重要 外部 API 呼び出し、ファイルシステム操作、データベースアクセスはすべてサービスレイヤーで完結させる必要があります。フロントエンドがこれらに直接アクセスしてはいけません。 :::

ステップ3: Routerの作成​

ファイル: packages/desktop/app/main/services/routers/FavoritesRouter.ts

import { z } from 'zod';
import { secureHandle } from '../../ipc/safe-handle';
import type { AuthService } from '../platform/auth';
import type { FavoritesService } from '../../content/favorites/FavoritesService';

export class FavoritesRouter {
  constructor(
    private readonly auth: AuthService,
    private readonly favorites: FavoritesService,
  ) {}

  register(): void {
    const validate = (token: string) => this.auth.validate(token);

    secureHandle(
      'favorites:list',
      async (_event, params: unknown) => {
        const { sessionId } = z.object({
          sessionId: z.string().optional(),
        }).parse(params ?? {});
        return this.favorites.list(sessionId);
      },
      validate,
    );

    secureHandle(
      'favorites:create',
      async (_event, params: unknown) => {
        const input = z.object({
          sessionId: z.string(),
          messageId: z.string(),
          note: z.string().optional(),
        }).parse(params);
        return this.favorites.create(input);
      },
      validate,
    );

    secureHandle(
      'favorites:update',
      async (_event, params: unknown) => {
        const { id, note } = z.object({
          id: z.string(),
          note: z.string().optional(),
        }).parse(params);
        return this.favorites.update(id, { note });
      },
      validate,
    );

    secureHandle(
      'favorites:delete',
      async (_event, params: unknown) => {
        const { id } = z.object({
          id: z.string(),
        }).parse(params);
        return this.favorites.delete(id);
      },
      validate,
    );
  }
}

主要なパターンの説明:

  • secureHandle(channel, handler, validate) — 統一されたセキュアなIPCハンドラ
    • channel — IPCチャンネル名（形式: domain:action）
    • handler — 非同期ハンドラ関数。第1引数は event、第2引数はトークンを除いた params
    • validate — トークン検証関数
  • Zodバリデーション: 悪意のある入力を防ぐため、すべてのパラメータはZodバリデーションを通過する必要があります

ステップ4: Routerの登録​

ファイル: packages/desktop/app/main/services/routers/index.ts

// 1. RouterとServiceをインポート
import { FavoritesRouter } from './FavoritesRouter';
import { FavoritesService } from '../../content/favorites/FavoritesService';

// 2. registerAllRouters() 内でインスタンスを作成して登録
export function registerAllRouters(deps: RouterDependencies) {
  // ... 既存のルーター登録 ...

  // FavoritesServiceとRouterを作成
  const favoritesService = new FavoritesService(deps.db);
  const favoritesRouter = new FavoritesRouter(deps.auth, favoritesService);
  favoritesRouter.register();

  // ... 他のコード ...
}

サービスに新しい依存関係が必要な場合は、同時に RouterDependencies インターフェースも更新してください。

ステップ5: Preload経由での公開​

ファイル: packages/desktop/app/preload/index.ts

api オブジェクトに新しい名前空間を追加します:

const api = {
  // ... 既存の名前空間 ...

  favorites: {
    list: (sessionId?: string) =>
      invoke('favorites:list', sessionId ? { sessionId } : undefined),
    create: (input: { sessionId: string; messageId: string; note?: string }) =>
      invoke('favorites:create', input),
    update: (id: string, note?: string) =>
      invoke('favorites:update', { id, note }),
    delete: (id: string) =>
      invoke('favorites:delete', { id }),
  },
};

また、フロントエンドの window.api が適切な型ヒントを得られるよう、@shared/contracts.ts の DesktopApi インターフェースにも型宣言を追加してください。

ステップ6: フロントエンドHookの作成​

ファイル: packages/renderer/src/features/favorites/hooks/useFavorites.ts

import { useCallback, useEffect, useState } from 'react';

import type { Favorite } from '@shared/contracts/favorites-types';

export function useFavorites(sessionId?: string) {
  const [favorites, setFavorites] = useState<Favorite[]>([]);
  const [loading, setLoading] = useState(true);

  const refresh = useCallback(async () => {
    setLoading(true);
    try {
      const result = await window.api.favorites.list(sessionId);
      setFavorites(result);
    } finally {
      setLoading(false);
    }
  }, [sessionId]);

  useEffect(() => {
    refresh();
  }, [refresh]);

  const addFavorite = useCallback(
    async (messageId: string, note?: string) => {
      if (!sessionId) return;
      await window.api.favorites.create({ sessionId, messageId, note });
      await refresh();
    },
    [sessionId, refresh],
  );

  const removeFavorite = useCallback(
    async (id: string) => {
      await window.api.favorites.delete(id);
      await refresh();
    },
    [refresh],
  );

  return { favorites, loading, addFavorite, removeFavorite, refresh };
}

ステップ7: UIコンポーネントの作成​

ファイル: packages/renderer/src/features/favorites/components/FavoritesList.tsx

import { Star, Trash2 } from 'lucide-react';

import { Button } from '@/components/ui/button';
import { useFavorites } from '@/features/favorites/hooks/useFavorites';

interface FavoritesListProps {
  sessionId: string;
}

export function FavoritesList({ sessionId }: FavoritesListProps) {
  const { favorites, loading, removeFavorite } = useFavorites(sessionId);

  if (loading) {
    return <div className="animate-pulse p-4">Loading...</div>;
  }

  if (favorites.length === 0) {
    return (
      <div className="flex flex-col items-center gap-2 p-8 text-muted-foreground">
        <Star className="h-8 w-8" />
        <p>No favorites yet</p>
      </div>
    );
  }

  return (
    <div className="space-y-2 p-4">
      {favorites.map((fav) => (
        <div
          key={fav.id}
          className="flex items-center justify-between rounded-lg bg-surface-1 p-3"
        >
          <div className="min-w-0 flex-1">
            <p className="truncate text-sm text-foreground">{fav.note}</p>
            <p className="text-xs text-muted-foreground">{fav.createdAt}</p>
          </div>
          <Button
            variant="ghost"
            size="icon"
            onClick={() => removeFavorite(fav.id)}
          >
            <Trash2 className="h-4 w-4" />
          </Button>
        </div>
      ))}
    </div>
  );
}

ステップ8: i18nの追加​

en、zh、ja の翻訳ファイルを作成します:

ファイル: packages/renderer/src/locales/{en,zh,ja}/favorites.json

{
  "favorites.title": "Favorites",
  "favorites.empty": "No favorites yet",
  "favorites.add": "Add to Favorites",
  "favorites.remove": "Remove from Favorites",
  "favorites.note": "Note"
}

チェックリスト​

PRを提出する前に、以下を確認してください:

  • フロントエンドはユーザー入力と設定パラメータのみを渡している（APIキーなどの機密データは渡さない）
  • バックエンドがすべての外部呼び出し（API、ファイルシステム、データベース）を処理している
  • フロントエンドに返されるデータは最終形態である（フロントエンドが処理して再送信する必要がない）
  • base64などの大容量データをフロントエンドで処理してバックエンドに送り返していない
  • RouterのパラメータがZodで検証されている
  • 新しいRouterが registerAllRouters() に登録されている
  • Preload APIのメソッドシグネチャが DesktopApi 型定義と一致している
  • i18nファイルが3言語すべてで更新されている
  • npm run lint がエラーなしで通過する

ファイル参照一覧​

レイヤーパス
共有型packages/desktop/app/shared/contracts/
バックエンドサービスpackages/desktop/app/main/services/
IPC Routerpackages/desktop/app/main/services/routers/
Router登録packages/desktop/app/main/services/routers/index.ts
Preloadスクリプトpackages/desktop/app/preload/index.ts
フロントエンドHookpackages/renderer/src/features/<feature>/hooks/ （クロスフィーチャーのHookは shared/hooks/ に配置）
フロントエンドコンポーネントpackages/renderer/src/features/<feature>/components/ （共有UIは components/ui/ に配置）
i18npackages/renderer/src/locales/