orpc-contract-first
Guide for implementing oRPC contract-first API patterns in Dify frontend. Triggers when creating new API contracts, adding service endpoints, integrating TanStack Query with typed contracts, or migrating legacy service calls to oRPC. Use for all API layer work in web/contract
Installation
Pick a client and clone the repository into its skills directory.
Installation
About this skill
Guide for implementing oRPC contract-first API patterns in Dify frontend. Triggers when creating new API contracts, adding service endpoints, integrating TanStack Query with typed contracts, or migrating legacy service calls to oRPC. Use for all API layer work in web/contract and web/service directories.
How to use
Utwórz nowy plik kontraktu w katalogu web/contract/console/{domena}.ts. Zaimportuj base z ../base oraz type z @orpc/contract, następnie zdefiniuj trasę zawierającą path, method, input i output zgodnie ze schematem {params, query?, body?}.
Zarejestruj kontrakt w pliku web/contract/router.ts, importując go bezpośrednio z pliku domeny (bez barrel files). Zagnieżdż trasę pod odpowiednim prefixem API — na przykład wszystkie trasy /billing/* powinny znaleźć się w obiekcie billing: {}.
Utwórz hook w pliku web/service/use-{domena}.ts, który będzie korzystać z consoleQuery.{grupa}.{kontrakt}.queryKey() do generowania kluczy zapytań oraz consoleClient.{grupa}.{kontrakt}() do wykonywania wywołań API.
Dla parametrów ścieżki użyj notacji {paramName} w polu path i dopasuj je w obiekcie params. Upewnij się, że struktura wejścia zawsze odpowiada formatowi {params, query?, body?}.
Importuj typy z @/types/ i używaj helpera type
() do definiowania typów. Wyeksportuj typ ConsoleInputs z routera, aby zapewnić pełną typizację w całej aplikacji. Jeśli migrujesz stare wywołania serwisów, zastąp je nowymi hookami oRPC i upewnij się, że wszystkie trasy są zagnieżdżone w routerze zgodnie z prefixami API.