docyrus-app-dev

Original：🇺🇸 English

Translated

Build React TypeScript web applications using Docyrus as a backend. Use when creating or modifying apps that authenticate with Docyrus OAuth2, fetch/mutate data via the @docyrus/api-client library, use auto-generated collections for CRUD operations, or build queries with filters, aggregations, formulas, pivots, and child queries against Docyrus data sources. Triggers on tasks involving @docyrus/api-client, @docyrus/signin, Docyrus collections, data source queries, or Docyrus-backed React app development.

2installs

Sourcedocyrus/agent-skills

Added on2026-02-14

NPX Install

npx skill4agent add docyrus/agent-skills docyrus-app-dev

SKILL.md Content

View Translation Comparison →

Docyrus App Developer

Build React TypeScript web apps with Docyrus as the backend. Authenticate via OAuth2 PKCE, query data sources with powerful filtering/aggregation, and follow established patterns.

Tech Stack

React 19 + TypeScript + Vite
TanStack Router (code-based), TanStack Query (server state)
Tailwind CSS v4, shadcn/ui components
```
@docyrus/api-client
```
(REST client) +
```
@docyrus/signin
```
(auth provider)
Auto-generated collections from OpenAPI spec

Quick Start: New App Setup

Wrap root with
```
DocyrusAuthProvider
```
:

tsx

import { DocyrusAuthProvider } from '@docyrus/signin'

<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <QueryClientProvider client={queryClient}>
    <RouterProvider router={router} />
  </QueryClientProvider>
</DocyrusAuthProvider>

In App.tsx, sync API client for collections:

tsx

const { status } = useDocyrusAuth()
const client = useDocyrusClient()

useEffect(() => {
  if (client) setApiClient(client)
}, [client])

if (status === 'loading') return <Spinner />
if (status === 'unauthenticated') return <SignInButton />

Use collections in hooks:

tsx

const { data: projects } = useQuery({
  queryKey: ['projects'],
  queryFn: () => baseProjectCollection.list({
    columns: ['name', 'status', 'record_owner(firstname,lastname)'],
    filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
    orderBy: 'created_on DESC',
    limit: 50,
  }),
})

Critical Rules

Always send
columns
in
```
.list()
```
and
```
.get()
```
calls. Without it, only
```
id
```
is returned.
Collections only work after auth —
```
setApiClient(client)
```
must be called first.
Data source endpoints are dynamic — they only exist if the data source is defined in the tenant's OpenAPI spec.
Use
id
field for
```
count
```
calculations. Use the actual field slug for
```
sum
```
,
```
avg
```
,
```
min
```
,
```
max
```
.
Child query keys must appear in
columns
— e.g., if childQuery key is
```
orders
```
, include
```
'orders'
```
in the columns array.
Formula keys must appear in
columns
— e.g., if formula key is
```
total
```
, include
```
'total'
```
in the columns array.
Use
UsersCollection.getMyInfo()
for current user profile, not a direct API call.

Collection CRUD Methods

Every generated collection provides:

typescript

collection.list(params?: ICollectionListParams)  // Query with filters, sort, pagination
collection.get(id, { columns })                   // Single record
collection.create(data)                           // Create
collection.update(id, data)                       // Partial update
collection.delete(id)                             // Delete one
collection.deleteMany({ recordIds })              // Delete many

API endpoint pattern:

/v1/apps/{appSlug}/data-sources/{slug}/items

Query Capabilities Summary

The

.list()

method supports:

Feature	Purpose
`columns`	Select fields, expand relations `field(subfields)` , alias `alias:field` , spread `...field()`
`filters`	Nested AND/OR groups with 50+ operators (comparison, date shortcuts, user-related)
`filterKeyword`	Full-text search
`orderBy`	Sort by fields with direction, including related fields
`limit` / `offset`	Pagination (default 100)
`fullCount`	Return total count alongside results
`calculations`	Aggregations: count, sum, avg, min, max with grouping
`formulas`	Computed virtual columns (simple functions, block AST, correlated subqueries)
`childQueries`	Fetch related child records as nested JSON arrays
`pivot`	Cross-tab matrix queries with date range series
`expand`	Return full objects for relation/user/enum fields instead of IDs

For query details, read:

references/query-guide.md

TanStack Query Pattern