nextjs-fastapi-conventions

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Next.js + FastAPI Conventions

Single source of truth for architecture, code quality, and testing in
Next.js + FastAPI full-stack projects.

## Project Stack

- **Frontend:** Next.js 16 (App Router) + React 19 + shadcn/ui + Tailwind CSS
  v4 (TypeScript, in `frontend/`)
- **Backend:** FastAPI + Uvicorn + Pydantic (Python 3.11+, in `backend/`)

## Architecture

### BFF Pattern

The browser NEVER calls FastAPI directly. All backend communication flows
through the Next.js server layer:
- **Server Actions** (`app/actions.ts`) handle mutations. Client components call
  these; they run on the Next.js server and proxy to FastAPI.
- **API Routes** (`app/api/*/route.ts`) exist ONLY for external consumers
  (health checks, webhooks), NOT for frontend use.

### Type Safety (Zod Contracts)

Every FastAPI response is validated on the frontend with Zod:
- `lib/contracts.ts`: Zod schemas mirroring Pydantic models.
- `lib/backend-client.ts`: `backendJson()` fetches + validates against Zod.
- Contract breaks fail fast with `BackendRequestError`.

**New endpoint checklist:**
1. Pydantic response model in `backend/api/schemas.py`.
2. Matching Zod schema in `frontend/lib/contracts.ts`.
3. Contract test in `frontend/tests/contracts.test.ts`.
4. `backendJson()` with schema in Server Action.

### Components

- **Server Components** (default): fetch data, pass as props.
- **Client Components** (`'use client'`): interactivity, browser APIs, hooks.

### React 19

- `useActionState` (NOT deprecated `useFormState`).
- Explicit state types (e.g. `GreetingState` in `lib/greeting-state.ts`).

### Backend Structure

- Lifespan via `@asynccontextmanager` (NOT `@app.on_event`).
- `pydantic-settings` for typed config from env vars.
- Versioned routers under `api/v1/`.
- Every endpoint declares `response_model` and returns a Pydantic model.

## Code Quality

### Python

- Async endpoints, `httpx.AsyncClient` (not `requests`).
- Type hints everywhere. `Annotated` for FastAPI params.
- Docstrings on modules, classes, public functions.
- `HTTPException` for API errors. No swallowed exceptions.
- Import grouping: stdlib | third-party | local.

### TypeScript

- `strict: true`. Never `any` (prefer `unknown` + narrowing).
- Zod for all external data; derive types with `z.infer<>`.
- Server Actions: `'use server'`, return typed state objects.
- shadcn/ui components from `components/ui/`.
- Import grouping: React/Next.js | third-party | local `@/` (components > lib >
  types).
- Tailwind v4 semantic tokens (`text-foreground`, `bg-muted`), not raw colours.

### Styling

- Tailwind utility classes in JSX. `cn()` from `lib/utils.ts` for conditional
  classes.
- Semantic tokens from `@theme`, not raw colour values.
- Mobile-first responsive (`sm:`, `md:`, `lg:`).
- CVA for component variants. Sonner for toasts. next-themes for theming.

### Tailwind v4 Runtime Theming

- Treat Tailwind v4 theme variables as part of the runtime contract, not as
  ordinary CSS constants. Read the project's actual `globals.css`/theme setup
  before changing visual states.
- If dark mode is driven by `next-themes` with `attribute="class"`, ensure
  Tailwind's `dark:` variant is also class-driven (for example with
  `@custom-variant dark (&:where(.dark, .dark *));`). Do not assume `.dark`
  affects Tailwind utilities when the compiled CSS still uses
  `prefers-color-scheme`.
- Use `@theme inline` only when utilities should inline a referenced value.
  Do not use it for semantic colours that must change at runtime between light
  and dark themes; compiled utilities may freeze light-mode literals such as
  `#ffffff` or `#e2e8f0`.
- For semantic colours that must respond to theme changes, prefer utilities
  that compile to runtime CSS variables, explicit arbitrary values such as
  `bg-[var(--color-card)]`, or small custom CSS rules that use `var(...)`.
- When debugging Tailwind v4 styling, inspect the generated CSS or browser
  computed styles before changing specificity. Cascade layers, `!important`,
  and `@theme inline` can make source CSS misleading.

### File Organisation

- Pages in `app/` (App Router). Reusable components in `components/`.
- shadcn/ui in `components/ui/` (don't edit directly).
- Shared utils/types in `lib/`. Import via `@/`.

## Testing

- Follow **testing-principles** for test intent; this section covers stack
  mechanics.

### Backend (pytest)

- `pytest` + `pytest-asyncio` (auto mode).
- `httpx.AsyncClient` + `ASGITransport` against FastAPI `app`.
- Assert status codes AND JSON payloads.
- `@pytest.mark.anyio` for async tests.

From wtsi-hgi/agentskills, MIT.

More from wtsi-hgi/agentskills