32 lines
2.6 KiB
Markdown
32 lines
2.6 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- `src/app` hosts the App Router; use `(auth)` and `(main)` route groups and keep route-only components inside their segment folders.
|
||
- `src/components` holds shared UI; keep primitives in `components/ui` and group feature widgets under clear folder names.
|
||
- `src/lib`, `src/services`, and `src/utils` house shared logic, API clients, and helpers; extend an existing module before adding a new directory.
|
||
- Mock handlers live in `src/mocks`, MSW’s worker sits in `public/mockServiceWorker.js`, localization bundles under `public/locales`, and generated docs go to `docs/`.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `npm run dev` starts the Turbopack dev server with MSW auto-registration when `NEXT_PUBLIC_ENABLE_MOCK=true`.
|
||
- `npm run build` compiles the production bundle; run after routing or configuration changes.
|
||
- `npm run start` serves the built app and mirrors production runtime.
|
||
- `npm run lint` applies the Next.js ESLint preset; resolve warnings before review.
|
||
- `npm run i18n:scan`, `npm run i18n:scan-custom`, and `npm run i18n:convert` refresh translation keys and write `docs/copy-audit.xlsx`.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- TypeScript is required; keep strict types at module boundaries and define payload interfaces explicitly.
|
||
- Follow the house formatting: two-space indentation, double quotes, no semicolons, and Tailwind classes composed with `cn`.
|
||
- Use PascalCase for React components, camelCase for utilities, `use` prefix for hooks, and kebab-case file names in routes.
|
||
- Reuse theme tokens and shared icons through design-system helpers; avoid ad-hoc color values or inline SVG copies.
|
||
|
||
## Testing Guidelines
|
||
- There is no global Jest/Vitest runner; smoke tests such as `src/utils/textParser.test.ts` execute with `npx tsx <path>`—mirror that pattern for quick unit checks.
|
||
- Keep exploratory scripts or `.test.ts` files beside the code they exercise and strip console noise before shipping.
|
||
- Prioritize integration checks through the dev server plus MSW, and document manual test steps in the PR when automation is absent.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Commit subjects are present-tense, sentence-style summaries (see `git log`); add rationale in the body when touching multiple areas.
|
||
- Scope each branch to a vertical slice (`feature/`, `fix/`, or `chore/`) and rebase on `main` before review.
|
||
- PRs need a concise summary, screenshots for UI updates, environment-variable callouts, and links to related issues or docs.
|
||
- Flag data, security, or localization assumptions so reviewers can validate configuration changes quickly.
|