docyrus-app-dev
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.
How do I install this agent skill?
npx skills add https://github.com/docyrus/agent-skills --skill docyrus-app-devIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The docyrus-app-dev skill provides a comprehensive framework for building React applications on the Docyrus platform. It leverages official vendor libraries for authentication, API interactions, and automated code generation. All external commands and package installations identified are restricted to the vendor's official tools and ecosystem, adhering to standard development workflows.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · No issues
- Runlayerpass
2/6 files flagged
What does this agent skill do?
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:
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, check auth and use collection hooks:
const { status } = useDocyrusAuth()
const { getMyInfo } = useUsersCollection()
if (status === 'loading') return <Spinner />
if (status === 'unauthenticated') return <SignInButton />
- Use collection hooks in components:
const { list } = useBaseProjectCollection()
const { data: projects } = useQuery({
queryKey: ['projects'],
queryFn: () => 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
columnsin.list()and.get()calls. Without it, onlyidis returned. - Collections are React hooks — call
useBaseProjectCollection(),useUsersCollection(), etc. inside React components. They useuseDocyrusClient()internally for authenticated API access. - Data source endpoints are dynamic — they only exist if the data source is defined in the tenant's OpenAPI spec.
- Use
idfield forcountcalculations. Use the actual field slug forsum,avg,min,max. - Child query keys must appear in
columns— e.g., if childQuery key isorders, include'orders'in the columns array. - Formula keys must appear in
columns— e.g., if formula key istotal, include'total'in the columns array. - Use
useUsersCollection().getMyInfo()for current user profile, not a direct API call.
Regenerating Collections After Schema Changes
When data sources or fields are created, updated, or deleted via the docyrus-architect MCP tools, the app's auto-generated collections become stale. To resync:
- Call
regenerate_openapi_spec(architect MCP) to rebuild and upload the tenant's OpenAPI spec - Download the new spec into the repo, overwriting the existing file:
curl -o openapi.json "<publicUrl returned from step 1>" - Regenerate collections:
pnpx @docyrus/tanstack-db-generator openapi.json
Always run all three steps together — a stale openapi.json or outdated collections will cause missing or incorrect endpoints at runtime.
Collection CRUD Methods
Every generated collection is a React hook that returns CRUD methods:
const { list, get, create, update, delete: deleteOne, deleteMany } = useBaseProjectCollection()
list(params?: ICollectionListParams) // Query with filters, sort, pagination
get(id, { columns }) // Single record
create(data) // Create
update(id, data) // Partial update
deleteOne(id) // Delete one
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/formula details, read:
references/data-source-query-guide.mdreferences/formula-design-guide-llm.md
TanStack Query Pattern
// Query hook — call collection hook inside the component, pass methods to TanStack Query
function useProjects(params?: ICollectionListParams) {
const { list } = useBaseProjectCollection()
return useQuery({
queryKey: ['projects', 'list', params],
queryFn: () => list({ columns: PROJECT_COLUMNS, ...params }),
})
}
// Mutation hook
function useCreateProject() {
const { create } = useBaseProjectCollection()
const qc = useQueryClient()
return useMutation({
mutationFn: (data: Record<string, unknown>) => create(data),
onSuccess: () => { void qc.invalidateQueries({ queryKey: ['projects'] }) },
})
}
References
Read these files when you need detailed information:
references/api-client-and-auth.md— RestApiClient API, @docyrus/signin hooks, auth provider config, interceptors, error handling, SSE/streaming, file upload/downloadreferences/data-source-query-guide.md— Up-to-date query payload guide: columns, filters, orderBy, pagination, calculations, formulas, child queries, pivots, and operator referencereferences/formula-design-guide-llm.md— Up-to-date formula design guide for building and validatingformulaspayloadsreferences/collections-and-patterns.md— Generated collection hooks, useUsersCollection, TanStack Query/mutation hook patterns, query key factories, app bootstrap flow, routing setup, API endpoints
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/docyrus/agent-skills/docyrus-app-dev">View docyrus-app-dev on skillZs</a>