#346 Co-authored-by: miteruzo <miteruzo@naver.com> Reviewed-on: #347
This commit was merged in pull request #347.
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
# 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`:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
Reference in New Issue
Block a user