AGENTS.md

1# Frontend
2 
3This file provides guidance to coding agents when working with the frontend.
4 
5## Essential Commands
6 
7```bash
8# Install dependencies
9pnpm i
10 
11# Generate API client from OpenAPI spec
12pnpm generate:api
13 
14# Start development server
15pnpm dev
16 
17# Run E2E tests
18pnpm test
19 
20# Run Storybook for component development
21pnpm storybook
22 
23# Build production
24pnpm build
25 
26# Format and lint
27pnpm format
28 
29# Type checking
30pnpm types
31```
32 
33### Pre-completion Checks (MANDATORY)
34 
35After making **any** code changes in the frontend, you MUST run the following commands **in order** before reporting work as done, creating commits, or opening PRs:
36 
371. `pnpm format` — auto-fix formatting issues
382. `pnpm lint` — check for lint errors; fix any that appear
393. `pnpm types` — check for type errors; fix any that appear
40 
41Do NOT skip these steps. If any command reports errors, fix them and re-run until clean. Only then may you consider the task complete. If typing keeps failing, stop and ask the user.
42 
434. `pnpm test:unit` — run integration tests; fix any failures
44 
45### Code Style
46 
47- Fully capitalize acronyms in symbols, e.g. `graphID`, `useBackendAPI`
48- Use function declarations (not arrow functions) for components/handlers
49- No `dark:` Tailwind classes — the design system handles dark mode
50- Use Next.js `<Link>` for internal navigation — never raw `<a>` tags
51- No `any` types unless the value genuinely can be anything
52- No linter suppressors (`// @ts-ignore`, `// eslint-disable`) — fix the actual issue
53- **File length** — keep files under ~200 lines; extract sub-components or hooks into their own files when a file grows beyond this
54- **Function/component length** — keep render functions and hooks under ~50 lines; extract named helpers or sub-components when they grow longer
55 
56## Architecture
57 
58- **Framework**: Next.js 15 App Router (client-first approach)
59- **Data Fetching**: Type-safe generated API hooks via Orval + React Query
60- **State Management**: React Query for server state, co-located UI state in components/hooks
61- **Component Structure**: Separate render logic (`.tsx`) from business logic (`use*.ts` hooks)
62- **Workflow Builder**: Visual graph editor using @xyflow/react
63- **UI Components**: shadcn/ui (Radix UI primitives) with Tailwind CSS styling
64- **Icons**: Hugeicons (stroke-rounded) only, rendered through the `Icon` atom
65- **Feature Flags**: LaunchDarkly integration
66- **Error Handling**: ErrorCard for render errors, toast for mutations, Sentry for exceptions
67- **Testing**: Vitest + React Testing Library + MSW for integration tests (primary), Playwright for E2E, Storybook for visual
68 
69## Environment Configuration
70 
71`.env.default` (defaults) → `.env` (user overrides)
72 
73## Feature Development
74 
75See @CONTRIBUTING.md for complete patterns. Quick reference:
76 
771. **Pages**: Create in `src/app/(platform)/feature-name/page.tsx`
78   - Extract component logic into custom hooks grouped by concern, not by component. Each hook should represent a cohesive domain of functionality (e.g., useSearch, useFilters, usePagination) rather than bundling all state into one useComponentState hook.
79     - Put each hook in its own `.ts` file
80   - Put sub-components in local `components/` folder
81   - Component props should be `type Props = { ... }` (not exported) unless it needs to be used outside the component
822. **Components**: Structure as `ComponentName/ComponentName.tsx` + `useComponentName.ts` + `helpers.ts`
83   - Use design system components from `src/components/` (atoms, molecules, organisms)
84   - Never use `src/components/__legacy__/*`
853. **Data fetching**: Use generated API hooks from `@/app/api/__generated__/endpoints/`
86   - Regenerate with `pnpm generate:api`
87   - Pattern: `use{Method}{Version}{OperationName}`
884. **Styling**: Tailwind CSS only, use design tokens, Hugeicons only
89   - Import icon data from `@hugeicons/core-free-icons` and render it with the `Icon` atom (`src/components/atoms/Icon/Icon.tsx`), e.g. `<Icon icon={Delete02Icon} size={16} />`.
90   - Never render `HugeiconsIcon` directly — the atom applies the 2px design-system stroke width.
91   - Type icon-carrying props with `IconSvgElement` from `@hugeicons/react`.
925. **Testing**: Integration tests are the default (~90%). See `TESTING.md` for full details.
93   - **New pages/features**: Write integration tests in `__tests__/` next to `page.tsx` using Vitest + RTL + MSW
94   - **API mocking**: Use Orval-generated MSW handlers from `@/app/api/__generated__/endpoints/{tag}/{tag}.msw.ts`
95   - **Run**: `pnpm test:unit` (integration/unit), `pnpm test` (Playwright E2E)
96   - **Storybook**: For design system components in `src/components/`
97   - **TDD**: Write a failing test first, implement, then verify
986. **Code conventions**:
99   - Use function declarations (not arrow functions) for components/handlers
100   - Do not use `useCallback` or `useMemo` unless asked to optimise a given function
101   - Do not type hook returns, let Typescript infer as much as possible
102   - Never type with `any` unless a variable/attribute can ACTUALLY be of any type
103   - avoid index and barrel files
104