frontend/AGENTS.md

Scope

These rules apply to work under frontend/.

This is a Vite + React + TypeScript app using TanStack Query, Tailwind CSS, Framer Motion, Radix UI-style components, MDX, and Zustand.

Use only scripts that exist in package.json:

npm run dev
npm run build
npm run lint
npm run preview

npm run build runs tsc -b && vite build, and postbuild runs node scripts/generate-sitemap.js.

There is currently no test script in package.json. Do not run or report npm test unless a test script is added.

After frontend changes, run:

npm run build
npm run lint

If either command cannot be run or fails, report the exact command and failure.

TypeScript is strict. tsconfig.app.json enables strict, noUnusedLocals, noUnusedParameters, erasableSyntaxOnly, noFallthroughCasesInSwitch, and noUncheckedSideEffectImports.
Keep types explicit at module boundaries, API helpers, and exported utilities.
Use import type for type-only imports.
Prefer existing shared types from src/types.ts before adding local duplicate types.
Preserve the repository's existing spacing style in TypeScript, including GNU-style spacing before call parentheses where it is already used.
Prefer single quotes for strings unless interpolation or escaping makes double quotes better.

Use function components.
Existing page components commonly export an anonymous function satisfying FC; match nearby file style when editing.
React hooks must be called unconditionally and at the top level of components or custom hooks.
Keep page-level components under src/pages.
Keep shared and feature components under src/components.
Use react-router-dom route params and navigation patterns already present in src/App.tsx.
Encode URL path-segment values with encodeURIComponent.

Use @tanstack/react-query for server state.
Query keys should come from src/lib/queryKeys.ts; add key builders there instead of using ad hoc arrays in components.
Fetch functions should live in domain helpers under src/lib, such as posts.ts, tags.ts, or wiki.ts.
Use useQueryClient().invalidateQueries with the shared root keys when mutations affect cached lists or detail views.
The app-wide QueryClient is configured in src/main.tsx; do not create additional clients in feature code.

Use src/lib/api.ts for HTTP calls.
The API wrapper attaches X-Transfer-Code from localStorage and converts non-blob responses to camelCase.
Send Rails snake_case params and request body keys where the backend expects them.
Do not bypass the API wrapper unless there is a specific reason, such as a third-party request outside the Rails API.
For blob responses, pass responseType: 'blob' so the wrapper does not camelCase the body.

The @ alias points to frontend/src.
Prefer @/... imports for app code instead of long relative paths.
Keep type imports separate with import type.
Match existing import grouping: external packages, app modules, then type imports.

Tailwind scans src/**/*.{html,js,ts,jsx,tsx,mdx}.
Use cn from src/lib/utils.ts for conditional class names and class merging.
Reuse components from src/components/common, src/components/layout, and src/components/ui before adding new primitives.
Keep Tailwind classes consistent with nearby components.
When adding dynamic tag color classes, update tailwind.config.js safelist if the class cannot be statically detected.
Do not introduce new UI libraries or production dependencies without approval.

ESLint uses @eslint/js, typescript-eslint, eslint-plugin-react-hooks, and eslint-plugin-react-refresh.
The hooks rules are enforced; fix hook ordering instead of disabling the rule.
react-refresh/only-export-components is enabled as a warning with allowConstantExport.
Build failures from unused locals or unused parameters are TypeScript errors, not lint-only issues.

Do not edit dist/ output directly.
Do not inspect or modify node_modules/ unless explicitly needed.
Keep generated build artifacts out of source changes unless the user asks for them.