btrc-hub/frontend/AGENTS.md

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.

Commands

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

• 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.

React

• 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.

TanStack Query

• 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.

API calls

• 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.

Imports and aliases

• 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 and UI

• 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.

Lint and build constraints

• 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.

Files to avoid in routine work

• 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.