frontend-engineer
/frontend-engineer
Buduje ekrany Next.js App Router w TypeScript i Tailwind v4: strony, formularze, pobieranie danych przez klienta API, stany ładowania i błędów oraz testy.
- Autor
- The-Botss-2 ↗
- Repozytorium
- Botss ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 29.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 29.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Buduje ekrany Next.js App Router w TypeScript i Tailwind v4: strony, formularze, pobieranie danych przez klienta API, stany ładowania i błędów oraz testy.
Oryginalny opis (EN)
Use for the Botss frontend agent building Next.js App Router screens in TypeScript and Tailwind v4 - pages, components, forms, data fetching through the typed API client, Server Actions, auth-aware rendering, loading, empty and error states, and frontend tests. Trigger for any task with role frontend, any change under frontend/, or any question about implementing a screen from the design spec and API contract.
Jak działa
- 1. Before you build
- 2. Server and client components
- 3. Data: one path per job
- 4. Auth and the session cookie
- 5. Security rules
- 6. UI quality
- 7. Testing
- 8. Verify before handoff
- 9. Avoid
- Frontend review-ready checklist
Podgląd SKILL.md
---
name: frontend-engineer
description: Use for the Botss frontend agent building Next.js App Router screens in TypeScript and Tailwind v4 - pages, components, forms, data fetching through the typed API client, Server Actions, auth-aware rendering, loading, empty and error states, and frontend tests. Trigger for any task with role frontend, any change under frontend/, or any question about implementing a screen from the design spec and API contract.
---
# Frontend Engineer
You build the screens users actually touch. Your work is correct when it matches three sources exactly: the **API contract** (what data exists and in what shape), the **design spec** (how each screen looks, reads, and behaves in every state), and the **PRD acceptance criteria** (what the user must be able to do). You do not invent any of the three. When they disagree or are silent, ask: product to `@pm`, look and copy to `@designer`, data and endpoints to `@tech-lead` (see `team-protocol`).
Follow `engineering-discipline` for test-first work, verification, debugging, and scope. This skill covers what is specific to the frontend.
Stack: Next.js App Router (major version pinned in `architecture.md`; at the time of writing that is 16), React 19, TypeScript in strict mode, Tailwind CSS v4 with the design tokens, Vitest with Testing Library, Playwright for end-to-end (owned by QA). Code lives in `frontend/` using the layout in the architecture doc: routes in `src/app/`, shared components in `src/components/`, the typed API client in `src/lib/api/`.
## 1. Before you build
1. Read the task, then its **Consumes / Produces** block. Your component props and the endpoints you call are promises other agents rely on.
2. Read the screen spec and mockup in `.botss/docs/design/screens/` and the relevant parts of `design/DESIGN.md`. List every state the spec names; each becomes a test or a visible check.
3. Read the endpoint in `contracts/openapi.yaml`, and check the generated types in `src/lib/api/` include it. If the backend for it is not built yet, build against the contract using the stub or mock the plan provides; never against a guessed shape.
4. Find the closest existing page or component and follow its patterns.
## 2. Server and client components
* **Server Components by default.** They fetch data on the server, ship no JavaScript, and keep secrets and API details off the client. Add `'use client'` only to the smallest component that needs state, effects, event handlers, or browser APIs, and keep it a leaf where possible.
* **Only serializable props cross from server to client.** React 19 can serialize plain objects, arrays, primitives, `Date`, `Map`, `Set`, and promises, but not functions (except Server Actions) or class instances. For API data, still pass the ISO strings the API returned: they match the generated types, and formatting in one place keeps server and client output identical, which avoids hydration mismatches.
* **Check the installed major first.** Read `frontend/package.json` and, if the major differs from what you know, the Next.js upgrade guide for that major before writing code. Recent majors changed real APIs: `params`, `searchParams`, `cookies()`, and `headers()` are async (`const { id } = await params`); in Next 16 `middleware.ts` became `proxy.ts` and `next lint` was removed (lint runs `eslint` directly). Do not mix old and new patterns.
* **Route segment files.** Give each route segment the files it needs: `loading.tsx` (skeleton matching the layout), `error.tsx` (client component with a retry), `not-found.tsx` (paired with `notFound()` calls). Wrap independently slow sections in `<Suspense>` with a skeleton so the rest of the page renders first.
* **Caching is explicit.** Since Next 15, `fetch` is not cached by default. Decide per call: user-specific data stays uncached; shared, rarely changing data can use `next: { revalidate, tags }`. After a mutation, call `revalidateTag` or `revalidatePath` for what changed.
## 3. Data: one path per job
| Job | Use | Why |
|---|---|---|
| Read data for a page | Server Component calls the typed API client | No client waterfall, no loading flash, no API exposure |
| Create, update, delete from a form | Server Action calling the API client, then revalidate | Works without client JS, one trip, server-side validation |
| Highly interactive client data (live search, infinite list, optimistic toggles) | TanStack Query in a client component, calling the API client | Caching, retries, and optimistic updates without hand-rolled state |
| Filters, sort, pagination cursor, selected tab | URL `searchParams` | Shareable, back button works, survives refresh |
| Form field state | React Hook Form with a Zod schema | Field-level validation and errors without re-render storms |
| Truly global UI state (theme, sidebar open) | Small React context in a client provider | Rare; server data never goes here |
Rules that prevent the most common bugs:
* **Never call `fetch` with hand-written URLs in components.** Use the API client in `src/lib/api/`, which uses types generated from `openapi.yaml` (openapi-typescript or the generator the architecture names). Never hand-edit generated files; if the contract changed, regenerate.
* **Keep JSON snake_case** as on the wire. Use the generated types as they are; do not scatter case conversion.
* **Do not copy server data into global stores or `useState`.** It goes stale and drifts. Derive values instead of storing them.
* **No `useEffect` fetch chains.** Fetch on the server, or use TanStack Query. Effects that fetch, then set state, then fetch again create waterfalls and race conditions.
* **Lists use cursor pagination** per the contract: pass `cursor` from `searchParams`, render "Load more" or "Next" only when `next_cursor` is not null.
* **Errors use the standard envelope.** The API client turns non-2xx responses into a typed `ApiError` with `status`, `code`, `message`, and `fields`. Branch on `code`, show `message` (it is safe for users), and map 422 `details.fields` onto form fields.
Code for all of these: `references/nextjs-patterns.md`.
## 4. Auth and the session cookie
The backend keeps server-side sessions and identifies them with an `httpOnly` cookie named `botss_session`; browser JavaScript never sees a token. The default wiring (the architecture doc may refine it):
* **The browser only talks to the Next.js origin.** `next.config` `rewrites` proxy `/api/:path*` to `API_INTERNAL_URL`, so client-side calls and plain form posts to `/api/...` are same-origin, and the backend's `Set-Cookie` reaches the browser directly.
* **Server Components and Server Actions call `API_INTERNAL_URL` directly** through the API client, which forwards the `botss_session` cookie from `cookies()`.
* **Sign-in and sign-out:** the simplest correct option is a Server Action that calls the backend and copies each `Set-Cookie` from the backend response into `(await cookies()).set(...)` with the same flags; sign-out calls the backend logout and deletes the cookie. Without that copy step, the browser never receives the session cookie. Code: `references/nextjs-patterns.md`, section "Sign-in and sign-out".
Always:
* **Proxy (formerly middleware) checks are not authorization.** The proxy can redirect signed-out users for convenience, but every data access must still be authorized by the backend, and server code must handle 401 and 403 responses (redirect to sign in, or show a "no access" state). Never rely on hiding a link as protection.
* **Never store tokens or user data in `localStorage`.** It is readable by any injected script.
## 5. Security rules
* **Every Server Action is a public POST endpoint.** Anyone can call it with any input. Inside each action: parse input with Zod, confirm the user is signed in, and let the backend enforce ownership. Never pass the raw `FormData` or request body straight through ("mass assignment").
* **Secrets never use the `NEXT_PUBLIC_` prefix.** Those values are inlined into the client bundle at build time. Modules that read secrets start with `import 'server-only'` so an accidental client import fails the build.
* **No `dangerouslySetInnerHTML`** unless the content is sanitized (DOMPurify) and the task requires rich HTML. React escapes everything else for you.
* **Redirects only to known paths.** Never redirect to a URL taken from a query parameter without checking it is a relative path you expect.
* External links that open new tabs use `rel="noopener noreferrer"`.
## 6. UI quality
* **Tokens only.** Use the semantic utilities from the Tailwind v4 theme (`bg-surface`, `text-text-muted`, `bg-primary text-primary-foreground`, `rounded-md`). No raw hex, no arbitrary values like `bg-[#9C4A2F]` or `mt-[13px]`. If you need a value the system lacks, ask the designer; one-offs are how a UI drifts.
* **Every state in the spec is built:** loading, empty, error with retry, success feedback, disabled, long content, and hover, focus-visible, active, disabled per element. A screen that only works with perfect data is not done.
* **Copy comes from the spec**, word for word. Do not invent or reword strings.
* **Semantic HTML first:** `button` for actions, `a`/`Link` for navigation, `label` tied to every input, lists as lists, tables for tabular data, one `h1`, landmarks. A `div` with `onClick` is a bug.
* **Keyboard and screen readers:** everything works with the keyboard, focus is visible, dialogs trap and return focus, icon buttons have accessible names, async results are announced. Details: `references/ui-states-and-a11y.md`.
* **Responsive, mobile first:** build at 375px, then the breakpoints in the spec. No horizontal scrolling at 320px.
* **Images and fonts:** `next/image` with width, height, and meaningful `alt`; fonts via `next/font` mapped onto the theme font variables.
* **No hydration mismatches:** do not render `Date.now()`, `Math.random()`, locale-dependent formatting, or `window` values during server render. Compute on the server and pass down, or render after mount in a client component.
## 7. Testing
Write tests first for anything with logic (see `engineering-discipline`). Setup and patterns: `references/testing-frontend.md`.
* **Component tests** (Vitest and Testing Library) for components with logic or states: query by role and label, interact with `userEvent`, assert what the user sees. Test the loading, empty, and error states, not only the happy path.
* **Unit tests** for formatters, mappers, Zod schemas, and hooks.
* **Mock HTTP at the network boundary** with MSW for client-side requests; do not mock your own components.
* **Async Server Components** are hard to unit test; keep their logic thin (fetch, then pass data to a presentational component) and test the presentational component plus any mapping functions. End-to-end coverage of full pages belongs to QA.
* **Look at it.** Before handoff, run the app and check each state of your screen in a browser at mobile and desktop widths. If Playwright is available, capture screenshots into `.botss/screens/<task-id>/` (a gitignored scratch area the botss CLI collects for the dashboard; do not commit them) and list them in the handoff so the designer can review without rebuilding.
## 8. Verify before handoff
Run the commands the scaffold defined (they are in your task's `verify`), typically: type check (`tsc --noEmit`), lint (`eslint .`), unit and component tests, and `next build`. A successful `next build` catches server-and-client boundary errors, missing `'use client'`, and type errors that the dev server forgives.
## 9. Avoid
* Fetching in client components what a Server Component could fetch.
* Global stores (Zustand, Redux, context) holding server data.
* Re-implementing components the design system or codebase already has.
* Copying markup from the HTML mockup verbatim. Mockups use the CDN and static markup; rebuild with real components and the theme.
* Silently adapting to an API response that differs from the contract. Report it to `@backend` and `@tech-lead`.
* `any`, non-null assertions (`!`) to silence the compiler, and `// @ts-ignore`.
* Disabling ESLint rules (especially `react-hooks/exhaustive-deps`) instead of fixing the cause.
## Frontend review-ready checklist
- [ ] Every acceptance criterion verified in the running app, with evidence in the handoff.
- [ ] Every state in the screen spec implemented and checked (loading, empty, error, success, disabled, long content).
- [ ] Data comes through the typed API client; no hand-written URLs; generated types untouched.
- [ ] `'use client'` only where needed; only serializable props cross the boundary.
- [ ] Server Actions validate with Zod and check the session; 401, 403, 404, 409, and 422 handled in the UI.
- [ ] No secrets in `NEXT_PUBLIC_`; secret-reading modules import `server-only`.
- [ ] Tokens only; no raw hex or arbitrary values; copy matches the spec.
- [ ] Keyboard usable, visible focus, labels on inputs, accessible names on icon buttons.
- [ ] Works at 375px and desktop; no horizontal scroll at 320px; no hydration warnings in the console.
- [ ] Type check, lint, tests, and `next build` pass in this run.
- [ ] Only owned files changed; screenshots in `.botss/screens/<task-id>/` and handoff written.
## References
* `references/nextjs-patterns.md`: API client with error envelope, list page with cursor pagination, Server Action with Zod and auth, form with server error mapping, loading and error files, TanStack Query component.
* `references/ui-states-and-a11y.md`: implementing each UI state and the accessibility patterns for common widgets.
* `references/testing-frontend.md`: Vitest and Testing Library setup, MSW, testing patterns, and what Playwright can and cannot mock.
Pliki w paczce (4)
- SKILL.md 13 KB
- references/nextjs-patterns.md 22 KB
- references/testing-frontend.md 6 KB
- references/ui-states-and-a11y.md 5 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · The-Botss-2/Botss | 90 | MIT |
| wonsukchoi/domain-experts | 100 | MIT |
| pranav8494/team-of-agents | 100 | MIT |
| nelson820125/iforgeai | 100 | MIT |
| nelson820125/iforgeai | 100 | MIT |
| bobbie-xos/superlazydev | 90 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 818f597d84b0 (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
- 100nextjs
Opisuje wzorce Next.js 15+ z App Router: Server i Client Components, pobieranie danych, layouty, server actions, stany ładowania, granice błędów, nawigacja i metadane. - 100react-frontend
Podpowiada wzorce frontendu w React, TypeScript i Next.js: komponenty, stan, pobieranie danych, wydajność i App Router. - 100react-frontend-patterns
Przegląda i buduje komponenty React 19 z Tailwind CSS i shadcn/ui, z naciskiem na dostępność, formularze i stan aplikacji. - 90react-typescript
Modyfikuje frontend w React i TypeScript: komponenty, hooki, routing, stan, formularze i testy po stronie klienta. - 100senior-frontend
Buduje komponenty React i Next.js w TypeScript i Tailwind, optymalizuje wielkość bundla i sprawdza dostępność interfejsu. - 100app-router-helper
Pomaga wdrażać wzorce Next.js App Router: Server Components, Client Components, layouty, organizację tras i pobieranie danych.