OpenParable
Skip to content
← Back to skills

Archestra Dev Frontend

Development
archestra-dev-frontend

Archestra Dev Frontend is an Agent Skill for development published in the archestra-ai/archestra repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when modifying Archestra frontend Next.js/React code, UI components, forms, TanStack Query hooks, generated API client usage, frontend copy, or documentation links.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/archestra-ai/archestra/blob/HEAD/.claude/skills/archestra-dev-frontend/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/archestra-dev-frontend, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Archestra Frontend Development

Use this skill before changing files under platform/frontend/ or frontend-facing shared code.

Commands

Run commands from platform/ unless specifically instructed otherwise.

pnpm codegen   # regenerates the OpenAPI spec and the API client
pnpm type-check
pnpm lint
pnpm test
pnpm knip   # flags unused exports; part of frontend check:ci

Data fetching

  • Use TanStack Query for data fetching.
  • Prefer useQuery over useSuspenseQuery with explicit loading states.
  • Prefer TanStack Query over prop drilling when a component can fetch data by identifier itself.
  • Only pass minimal identifiers, such as catalogId, needed for child components to fetch or filter their own data.
  • TanStack Query caching prevents duplicate requests when multiple components use the same query.

API clients

  • Frontend .query.ts files should never call the Archestra backend with fetch() directly — use the generated SDK. Raw fetch() is only for third-party APIs the SDK does not cover (e.g. GitHub, see lib/github/*.query.ts).
  • Run pnpm codegen first to ensure the generated SDK is up to date (codegen:api-client alone only exists inside @archestra/shared and needs the env var: CODEGEN=true pnpm --filter @archestra/shared codegen:api-client — without CODEGEN=true it reads a live localhost:9000 instead of the committed spec).
  • Use generated SDK methods instead of manual API calls for type safety and consistency.
  • Reuse API types from @archestra/shared, especially archestraApiTypes types such as archestraApiTypes.CreateXxxData["body"] and archestraApiTypes.GetXxxResponses["200"].
  • Do not define duplicate frontend API types when generated/shared types already exist.

Query error handling

  • Handle toasts in .query.ts files, not in components.
  • Define mutation success/error toasts in onSuccess and onError callbacks.
  • Queries must fail loud: call throwOnApiError(error) after the SDK call so the query enters its error state, then keep the existing success return (return data ?? []). Swallowing an error into a default makes an outage indistinguishable from a genuinely empty result, which is how an offline app showed "Add an LLM Provider Key".
  • throwOnApiError(error) toasts via handleApiError by default. Screens that render their own error state (e.g. a QueryLoadError retry panel gated on isLoadingError) pass { toastOnError: false } to avoid a redundant toast and a fresh toast on every retry. Detail endpoints where a 404 means "does not exist" rather than an outage pass { allowNotFound: true } and keep returning their null default for that case.
  • Mutations keep handleApiError(error) + throw toApiError(error) in the mutationFn.
  • Components should not use try/catch for API calls; API error handling belongs in .query.ts files.

UI components

  • Use shadcn/ui components only.
  • Add shadcn/ui components with npx shadcn@latest add <component>.
  • Prefer components from frontend/src/components/ui over plain HTML elements when a component exists.
  • Use Button over raw <button>, Input over raw <input>, and the matching UI component for selects and other controls.
  • Keep components small and focused, with extracted business logic where it improves clarity.
  • Keep frontend files flat where practical and avoid barrel files.
  • Only export what is needed externally.

Forms

  • Prefer useForm from react-hook-form over multiple useState hooks for form state.
  • Pass form objects to child components as form: UseFormReturn<FormValues> rather than passing individual setters.
  • Parent components should handle mutations and submission.
  • Form components should focus on rendering and validation UI.

Copy and documentation links

  • Do not hardcode Archestra in frontend UI copy.
  • Use const appName = useAppName(); and interpolate the app name so white-labeled deployments render correctly.
  • Always use getDocsUrl(DocsPage.PageName, "optional-anchor") from @archestra/shared for documentation links.
  • Never hardcode documentation URLs.

Test mocking

  • Frequently-mocked modules have Jest-style __mocks__ canonical mocks — activate with a bare vi.mock("<specifier>"); and configure per test via vi.mocked(...). Covered: @/lib/auth/auth.query, @/lib/organization.query, @/lib/config/config.query, @/lib/teams/team.query, @/lib/hooks/use-app-name, @/lib/clients/auth/auth-client (a memoized proxy — every path like authClient.signIn.email is a stable vi.fn()), plus root-level __mocks__/ for next/navigation and sonner.
  • Do not write a bespoke partial factory for those specifiers. Exception: a file that partially mocks @/lib/config/config may keep factories for the query mocks — the canonical mocks' importActual chain eagerly loads auth-client → config/config and breaks under a partial config mock.
  • The @ alias must stay declared in vitest.config.ts resolve.alias with an absolute path — tsconfig-paths-only aliasing silently breaks __mocks__ resolution (vitest-dev/vitest#8343).