Archestra Dev Frontend
Developmentarchestra-dev-frontendArchestra 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.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- 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
useQueryoveruseSuspenseQuerywith 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.tsfiles should never call the Archestra backend withfetch()directly — use the generated SDK. Rawfetch()is only for third-party APIs the SDK does not cover (e.g. GitHub, seelib/github/*.query.ts). - Run
pnpm codegenfirst to ensure the generated SDK is up to date (codegen:api-clientalone only exists inside@archestra/sharedand needs the env var:CODEGEN=true pnpm --filter @archestra/shared codegen:api-client— withoutCODEGEN=trueit reads a livelocalhost:9000instead of the committed spec). - Use generated SDK methods instead of manual API calls for type safety and consistency.
- Reuse API types from
@archestra/shared, especiallyarchestraApiTypestypes such asarchestraApiTypes.CreateXxxData["body"]andarchestraApiTypes.GetXxxResponses["200"]. - Do not define duplicate frontend API types when generated/shared types already exist.
Query error handling
- Handle toasts in
.query.tsfiles, not in components. - Define mutation success/error toasts in
onSuccessandonErrorcallbacks. - 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 viahandleApiErrorby default. Screens that render their own error state (e.g. aQueryLoadErrorretry panel gated onisLoadingError) 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 theirnulldefault for that case.- Mutations keep
handleApiError(error)+throw toApiError(error)in themutationFn. - Components should not use
try/catchfor API calls; API error handling belongs in.query.tsfiles.
UI components
- Use shadcn/ui components only.
- Add shadcn/ui components with
npx shadcn@latest add <component>. - Prefer components from
frontend/src/components/uiover plain HTML elements when a component exists. - Use
Buttonover raw<button>,Inputover 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
useFormfromreact-hook-formover multipleuseStatehooks 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
Archestrain 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/sharedfor documentation links. - Never hardcode documentation URLs.
Test mocking
- Frequently-mocked modules have Jest-style
__mocks__canonical mocks — activate with a barevi.mock("<specifier>");and configure per test viavi.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 likeauthClient.signIn.emailis a stablevi.fn()), plus root-level__mocks__/fornext/navigationandsonner. - Do not write a bespoke partial factory for those specifiers. Exception: a file that partially mocks
@/lib/config/configmay keep factories for the query mocks — the canonical mocks'importActualchain eagerly loadsauth-client→config/configand breaks under a partial config mock. - The
@alias must stay declared invitest.config.tsresolve.aliaswith an absolute path — tsconfig-paths-only aliasing silently breaks__mocks__resolution (vitest-dev/vitest#8343).