orpc-contract-first_skill

Overview

This skill guides contract-first oRPC API development for the Dify frontend, focused on the web/contract and web/service layers. It codifies where to add new contracts, how to register them in the router, and how to create typed service hooks. The goal is consistent, typed API surface and smooth migration of legacy calls to oRPC patterns.

How this skill works

The skill inspects project layout and enforces adding contracts under web/contract/console/{domain}.ts using the base contract and @orpc/contract types. It ensures routes declare path, method, and structured inputs (params, query?, body?) and that each domain contract is registered in web/contract/router.ts without barrel imports. For client usage it expects hooks in web/service/use-{domain}.ts that rely on consoleQuery.{group}.{contract}.queryKey() and consoleClient.{group}.{contract}() for typed calls.

When to use it

• When creating a new API contract for any console domain.
• When adding or grouping service endpoints under an API prefix (e.g., /billing).
• When integrating TanStack Query with typed oRPC contracts and query keys.
• When migrating legacy service calls to typed oRPC client methods.
• For all API layer work in web/contract and web/service directories.

Best practices

• Always use input structure { params, query?, body? } to keep shapes consistent.
• Declare path params as {paramName} and mirror them in params for type safety.
• Register domain contracts directly in router.ts; avoid barrel file imports.
• Group router entries by API prefix (billing: { invoices, ... }) to reflect URL structure.
• Import runtime types from @/types and wrap schemas with type<T>() helpers.

Example use cases

• Add a new marketplace endpoint: create web/contract/console/marketplace.ts and register it in router.ts.
• Migrate a legacy fetch call to consoleClient.billing.getInvoice() and use consoleQuery.billing.getInvoice.queryKey() for caching.
• Create a typed hook use-billing.ts that calls consoleClient.billing.bindPartnerStack() and invalidates keys after mutations.
• Define a route with path '/invoices/{invoiceId}' and ensure invoiceId appears in params.