docyrus-app-dev（docyrus 应用程序开发）

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, check auth and use collection hooks:

const { status } = useDocyrusAuth()
const { getMyInfo } = useUsersCollection()

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

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

1. Always send columns in .list() and .get() calls. Without it, only id is returned.
2. Collections are React hooks — call useBaseProjectCollection(), useUsersCollection(), etc. inside React components. They use useDocyrusClient() internally for authenticated API access.
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 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:

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 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:

For query/formula details, read:

• references/data-source-query-guide.md
• references/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/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 hooks, useUsersCollection, TanStack Query/mutation hook patterns, query key factories, app bootstrap flow, routing setup, API endpoints