Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

archestra-dev-frontend

/archestra-dev-frontend

Pomaga modyfikować frontend Archestra w Next.js i React: komponenty UI, formularze, hooki TanStack Query, wygenerowany klient API, teksty interfejsu i linki do dokumentacji.

Repozytorium
archestra ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pomaga modyfikować frontend Archestra w Next.js i React: komponenty UI, formularze, hooki TanStack Query, wygenerowany klient API, teksty interfejsu i linki do dokumentacji.

Oryginalny opis (EN)

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

Jak działa

  1. Commands
  2. File and folder naming
  3. Data fetching
  4. API clients
  5. Query error handling
  6. UI components
  7. Buttons
  8. Notices, warnings, and announcements
  9. Text nodes and machine translation
  10. Forms
Sekcje z nagłówków SKILL.md, w oryginale · 148 linii, 1 596 słów
Podgląd SKILL.md
---
name: archestra-dev-frontend
description: Use when modifying Archestra frontend Next.js/React code, UI components, forms, TanStack Query hooks, generated API client usage, frontend copy, or documentation links.
---

# Archestra Frontend Development

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

This is the skill for day-to-day platform UI work. For visual design direction on a greenfield, user-facing surface — a marketing or landing page, a generated app, a standalone page — see `design-taste-frontend` instead.

## Commands

Run commands from `platform/` unless specifically instructed otherwise.

```bash
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
```

## File and folder naming

`platform/frontend/AGENTS.md`, "Conventions", holds the table: `_parts/` for route-private folders, `use-<thing>.ts` hooks beside their feature, kebab-case names, and the closed list of dot suffixes. Biome enforces it, so a misnamed file fails `pnpm lint`.

## 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 `Input` over raw `<input>`, and the matching UI component for selects and other controls.

## Buttons

Never use a raw `<button>`; use `Button` with a standard size. `tools/biome-plugins/no-raw-button.grit` fails the build on a raw `<button>` outside `components/ui/`, and its diagnostics cannot be suppressed.

Pick the size by where the button sits:

- `sm` / `icon-sm` (32px) — the standard. Page and detail-page header actions, card and section actions, sticky save rows on a page, toolbars, filter bars, empty states, table row actions, pagination.
- `default` / `icon` (36px) — dialog and sheet footers, and buttons sharing a row with form inputs (inputs are 36px).
- `xs` / `icon-xs` (28px) — dense controls inside content: table cells, list items, chat messages, code blocks, notices.

Do not resize a `Button` with `className` (`h-*`, `size-*`, `px-*`, `py-*`, `text-xs`). Change the `size` prop instead. Layout, position and colour classes are fine. `h-auto` is fine on `link` buttons and multi-line content.

Selects and toggles that sit beside buttons take the same height: `SelectTrigger size="sm"` and `Toggle size="sm"` next to `sm` buttons.

A clickable surface that does not look like a button — a whole row, card, tile, listbox option, or a glyph inside a chip — uses `UnstyledButton` from `components/ui/unstyled-button.tsx`. Do not use it to dodge `Button`'s sizes.
- Keep components small and focused, with extracted business logic where it improves clarity.
- Keep frontend files flat where practical and avoid barrel files.
- Import helpers from focused `@/lib/utils/*` modules (`tailwind` for `cn`, `api` for API errors, `date-time` for dates). The `@/lib/utils` barrel eagerly loads unrelated modules, including `date-fns`, in every test or server module that imports it. Biome rejects that barrel path.
- Only export what is needed externally.

## Notices, warnings, and announcements

Render every notice, warning, error, or announcement through one of two shared
components. Do not hand-roll a notice. Do not restyle one with your own
colour, border, radius, or padding classes.

- `InlineNotice` (`components/ui/inline-notice.tsx`) is the default choice.
  Use it for a notice about the surface it sits on. Examples: a form that
  cannot reach a repository, a read-only panel, a validation failure. The
  variants are `warning` (the default), `error`, `info`, and `neutral`.
  Compose it in this order: the icon, a `<span className="font-medium">`
  title, an `<InlineNoticeText>` explanation, then an optional action with
  `className="ml-auto"`. Add the `floating` prop when the notice sits over
  content that scrolls under it.
- `Alert` (`components/ui/alert.tsx`) is a page-level banner. It is the
  content of its own row. Its body can hold several sentences, lists, or
  links. Its padding is too large inside a form or a dialog. Use
  `InlineNotice` there.

Extend `InlineNotice` when a new case does not fit. Add a variant, or let the
variant own the new colour. Do not add utility classes at the call site. Do
not write another bespoke notice div.

The app once carried about forty hand-rolled copies of these two components.
Those copies used four amber palettes and three paddings. This rule prevents
that.

The variant owns every colour, including the colour of the explanation. Never
give a child its own amber, red, or blue class. The two values drift apart
when a palette moves.

## Text nodes and machine translation

Chrome page-translate re-parents bare text nodes into `<font>` wrappers. React still holds the original nodes, so deleting one — or inserting an element before it — throws `NotFoundError` and crashes the page (facebook/react#11538, no upstream fix). Never let React add, remove, or replace a **bare** text node: wrap conditional text in an element so only elements move.

`tools/biome-plugins/no-conditional-bare-jsx-text.grit` fails the build on the shapes below, and its diagnostics cannot be suppressed with `biome-ignore` — write them wrapped in the first place:

- `{cond ? <Icon /> : "More"}` → `{cond ? <Icon /> : <span>More</span>}`.
- `{cond ? (<><Loader2 />Loading…</>) : ("Load more")}` → wrap both branches; the fragment's own bare text is deleted when the branch flips, so `<span>Loading…</span>` inside it and `<span>Load more</span>` for the string.
- `{saved && "Saved!"}` → `{saved && <span>Saved!</span>}`.
- `{n > 0 ? " and more" : ""}` → `{n > 0 ? <span> and more</span> : null}` — return `null`, never `""`, and keep the padding spaces inside the span.
- `<Button>{pending ? <Loader2 /> : <Icon />} Save</Button>` → wrap the label: `<span>Save</span>`. Same for a label expression: `<span>{agent ? "Update" : "Create"}</span>`.

The rule cannot see these; apply the convention by hand:

- A `ReactNode` prop or variable rendered next to a conditional sibling (`{icon}{label}`) — wrap it: `{icon}<span>{label}</span>` (`app/messaging-channels/layout.tsx`).
- Loading/empty/data branches whose roots are the **same tag** — React reconciles the element and deletes the bare status text in place. Wrap each branch's text (`<span>Loading tools…</span>`) or give the branches distinct `key`s.
- A shared component rendering a `ReactNode` slot inside an element that persists across content changes — key the wrapper by the content, as `components/form-dialog.tsx` and `components/ui/searchable-select.tsx` do.

Safe, do not churn: text→text updates (`{saving ? "Saving…" : "Save"}`), whole-element unmounts, and strings in attributes.

Wrapping splits a string across sibling elements, so Testing Library's default `getByText` stops matching. Scope to a container with `toHaveTextContent`, or use a function matcher constrained by tag — do not unwrap the span to satisfy a test.

## 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).

Wersje

W bazie nie ma innych skilli o nazwie archestra-dev-frontend.

Migawka bazy z 13.11.2026 · wersja paczki f9acd89b7223 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100archestra-dev-backend
    Pomaga dodawać i zmieniać backend Archestra: trasy, modele, serwisy, schematy żądań i odpowiedzi API, uprawnienia endpointów oraz OpenAPI i generowanie klienta API.
  • 100archestra-dev-e2e
    Pomaga pisać, debugować i uruchamiać testy e2e Playwright dla Archestra, w tym fikstury API i UI, testy z WireMock, lokalną i CI konfigurację oraz selektory.
  • 90react-typescript
    Modyfikuje frontend w React i TypeScript: komponenty, hooki, routing, stan, formularze i testy po stronie klienta.
  • 100react
    Pomaga tworzyć i zmieniać komponenty, hooki i elementy interfejsu w pakietach react-ui oraz ui-components.
  • 100frontend-patterns
    Podaje niezależne od frameworka wzorce React i Vue: kompozycję komponentów, hooki, TanStack Query, memoizację i error boundaries.
  • 100frontend
    Pomaga projektować strukturę komponentów React, decydować, gdzie powinien żyć stan, pobierać dane z TanStack Query, budować walidowane formularze i optymalizować renderowanie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.