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>

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

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

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 details, read: references/query-guide.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/query-guide.md — Full query payload reference: column syntax, all filter operators, aggregations, simple/block/subquery formulas, child queries, pivot tables, expand
• •references/collections-and-patterns.md — Generated collection structure, UsersCollection, TanStack Query/mutation hook patterns, query key factories, app bootstrap flow, routing setup, API endpoints