AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
Frontend
This file provides guidance to coding agents when working with the frontend.
Essential Commands
# Install dependencies
pnpm i
# Generate API client from OpenAPI spec
pnpm generate:api
# Start development server
pnpm dev
# Run E2E tests
pnpm test
# Run Storybook for component development
pnpm storybook
# Build production
pnpm build
# Format and lint
pnpm format
# Type checking
pnpm types
Pre-completion Checks (MANDATORY)
After 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:
pnpm format— auto-fix formatting issuespnpm lint— check for lint errors; fix any that appearpnpm types— check for type errors; fix any that appear
Do 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.
pnpm test:unit— run integration tests; fix any failures
Code Style
- Fully capitalize acronyms in symbols, e.g.
graphID,useBackendAPI - Use function declarations (not arrow functions) for components/handlers
- No
dark:Tailwind classes — the design system handles dark mode - Use Next.js
<Link>for internal navigation — never raw<a>tags - No
anytypes unless the value genuinely can be anything - No linter suppressors (
// @ts-ignore,// eslint-disable) — fix the actual issue - File length — keep files under ~200 lines; extract sub-components or hooks into their own files when a file grows beyond this
- Function/component length — keep render functions and hooks under ~50 lines; extract named helpers or sub-components when they grow longer
Architecture
- Framework: Next.js 15 App Router (client-first approach)
- Data Fetching: Type-safe generated API hooks via Orval + React Query
- State Management: React Query for server state, co-located UI state in components/hooks
- Component Structure: Separate render logic (
.tsx) from business logic (use*.tshooks) - Workflow Builder: Visual graph editor using @xyflow/react
- UI Components: shadcn/ui (Radix UI primitives) with Tailwind CSS styling
- Icons: Hugeicons (stroke-rounded) only, rendered through the
Iconatom - Feature Flags: read from the backend's
/api/feature-flagsby default, which answers from PostHog - Error Handling: ErrorCard for render errors, toast for mutations, Sentry for exceptions
- Testing: Vitest + React Testing Library + MSW for integration tests (primary), Playwright for E2E, Storybook for visual
Environment Configuration
.env.default (defaults) → .env (user overrides)
Feature Development
See @CONTRIBUTING.md for complete patterns. Quick reference:
- Pages: Create in
src/app/(platform)/feature-name/page.tsx- 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.
- Put each hook in its own
.tsfile
- Put each hook in its own
- Put sub-components in local
components/folder - Component props should be
type Props = { ... }(not exported) unless it needs to be used outside the component
- 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.
- Components: Structure as
ComponentName/ComponentName.tsx+useComponentName.ts+helpers.ts- Use design system components from
src/components/(atoms, molecules, organisms) - Never use
src/components/__legacy__/*
- Use design system components from
- Data fetching: Use generated API hooks from
@/app/api/__generated__/endpoints/- Regenerate with
pnpm generate:api - Pattern:
use{Method}{Version}{OperationName}
- Regenerate with
- Styling: Tailwind CSS only, use design tokens, Hugeicons only
- Import icon data from
@hugeicons/core-free-iconsand render it with theIconatom (src/components/atoms/Icon/Icon.tsx), e.g.<Icon icon={Delete02Icon} size={16} />. - Never render
HugeiconsIcondirectly — the atom applies the 2px design-system stroke width. - Type icon-carrying props with
IconSvgElementfrom@hugeicons/react.
- Import icon data from
- Testing: Integration tests are the default (~90%). See
TESTING.mdfor full details.- New pages/features: Write integration tests in
__tests__/next topage.tsxusing Vitest + RTL + MSW - API mocking: Use Orval-generated MSW handlers from
@/app/api/__generated__/endpoints/{tag}/{tag}.msw.ts - Run:
pnpm test:unit(integration/unit),pnpm test(Playwright E2E) - Storybook: For design system components in
src/components/ - TDD: Write a failing test first, implement, then verify
- New pages/features: Write integration tests in
- Code conventions:
- Use function declarations (not arrow functions) for components/handlers
- Do not use
useCallbackoruseMemounless asked to optimise a given function - Do not type hook returns, let Typescript infer as much as possible
- Never type with
anyunless a variable/attribute can ACTUALLY be of any type - avoid index and barrel files