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.

Do not create, modify, or run tests unless the user explicitly asks for test work. When the user asks for tests, keep working and rerun them until they pass or the remaining failure is clearly blocked.

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.
• Never write a TypeScript or TSX line longer than 99 characters.
• Aim to keep TypeScript and TSX lines within 79 characters where practical.
• Use 4-space logical indentation in TypeScript and TSX.
• For arrays, never put whitespace or a line break immediately before ].
• Keep the first element on the same line as [ by default.
• If an array would exceed the line limit, break after [ and indent elements by 4 spaces.
• In TypeScript and TSX only, replace every leading run of 8 spaces with a tab to reduce bytes.
• Treat one leading tab as exactly equivalent to 8 leading spaces.
• Use tabs only for leading indentation. Never replace spaces that occur after a non-space character on the same line.

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.
• Gate editing and other privileged controls with shared permission helpers such as canEditContent, instead of showing controls and relying only on a later API failure.
• 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.
• Prefer restrained, content-first UI chrome: avoid adding card backgrounds, heavy borders, or nested panel decoration unless the surrounding screen already uses them.
• Keep operational screens dense and direct; trim explanatory copy and use short Japanese labels that fit the control.
• Preserve existing Japanese tone and orthography in nearby UI text, including old-kana wording where the file already uses it.
• 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.

TSX formatting

• Preserve compact TSX expression shapes such as inline ternary branches and closing </div>) forms when nearby code uses them.
• For long Tailwind className strings, wrap across lines only when needed.
• Keep continuation indentation aligned with the 4-space logical indentation rule, using tabs only as leading 8-space compression.
• Do not add braces around if, else, or for bodies when the body is a single physical line.
• Always add braces around if, else, or for bodies when the body spans two or more physical lines, even if it is one statement.
• Avoid reformatting unrelated JSX.

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.