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

1. 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>

2. In App.tsx, sync API client for collections:

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

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

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

3. Use collections in hooks:

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

1. Always send columns in .list() and .get() calls. Without it, only id is returned.
2. Collections only work after auth — setApiClient(client) must be called first.
3. Data source endpoints are dynamic — they only exist if the data source is defined in the tenant's OpenAPI spec.
4. Use id field for count calculations. Use the actual field slug for sum, avg, min, max.
5. Child query keys must appear in columns — e.g., if childQuery key is orders, include 'orders' in the columns array.
6. Formula keys must appear in columns — e.g., if formula key is total, include 'total' in the columns array.
7. Use UsersCollection.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:

1. Call regenerate_openapi_spec (architect MCP) to rebuild and upload the tenant's OpenAPI spec
2. Download the new spec into the repo, overwriting the existing file:

   curl -o openapi.json "<publicUrl returned from step 1>"

3. 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 provides:

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:

For query/formula details, read:

• references/data-source-query-guide.md
• references/formula-design-guide-llm.md

TanStack Query Pattern

// Query hook
function useItems(params?: ICollectionListParams) {
  return useQuery({
    queryKey: ['items', 'list', params],
    queryFn: () => collection.list({ columns: COLUMNS, ...params }),
  })
}

// Mutation hook
function useCreateItem() {
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (data: Record<string, unknown>) => collection.create(data),
    onSuccess: () => { void qc.invalidateQueries({ queryKey: ['items'] }) },
  })
}

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/download
• references/data-source-query-guide.md — Up-to-date query payload guide: columns, filters, orderBy, pagination, calculations, formulas, child queries, pivots, and operator reference
• references/formula-design-guide-llm.md — Up-to-date formula design guide for building and validating formulas payloads
• references/collections-and-patterns.md — Generated collection structure, UsersCollection, TanStack Query/mutation hook patterns, query key factories, app bootstrap flow, routing setup, API endpoints