orpc-contract-first

Original：🇺🇸 English

Translated

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.

2installs

Sourcelanggenius/dify

Added on2026-02-04

NPX Install

npx skill4agent add langgenius/dify orpc-contract-first

SKILL.md Content

View Translation Comparison →

oRPC Contract-First Development

Project Structure

web/contract/
├── base.ts           # Base contract (inputStructure: 'detailed')
├── router.ts         # Router composition & type exports
├── marketplace.ts    # Marketplace contracts
└── console/          # Console contracts by domain
    ├── system.ts
    └── billing.ts

Workflow

Create contract in

web/contract/console/{domain}.ts

Import
```
base
```
from
```
../base
```
and
```
type
```
from
```
@orpc/contract
```
Define route with
```
path
```
,
```
method
```
,
```
input
```
,
```
output
```

Register in router at
```
web/contract/router.ts
```
- Import directly from domain file (no barrel files)
- Nest by API prefix:
```
billing: { invoices, bindPartnerStack }
```

Create hooks in

web/service/use-{domain}.ts

Use

consoleQuery.{group}.{contract}.queryKey()

for query keys

Use
```
consoleClient.{group}.{contract}()
```
for API calls

Key Rules

Input structure: Always use
```
{ params, query?, body? }
```
format
Path params: Use
```
{paramName}
```
in path, match in
```
params
```
object
Router nesting: Group by API prefix (e.g.,
```
/billing/*
```
→
```
billing: {}
```
)
No barrel files: Import directly from specific files
Types: Import from
```
@/types/
```
, use
```
type<T>()
```
helper

Type Export

typescript

export type ConsoleInputs = InferContractRouterInputs<typeof consoleRouterContract>