45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
# Repository Guidelines
|
||
|
||
This document summarizes how to work effectively in this repo.
|
||
|
||
## Project Structure & Module Organization
|
||
- `src/app`: Next.js App Router (Next 14). Localized routes under `src/app/[locale]`. Global styles in `src/app/globals.css`.
|
||
- `src/components`: Reusable UI in PascalCase (e.g., `Header.tsx`).
|
||
- `src/servers`: Server-side data and actions (DB, search, works APIs).
|
||
- `src/libs`: Integrations and utilities (Stripe, Replicate, R2, DB helpers).
|
||
- `src/configs`: App/third‑party config (e.g., `stripeConfig.ts`, `openaiConfig.ts`).
|
||
- `src/i18n`, `src/context`: Localization and React context.
|
||
- `public`: Static assets. `sql/tables`: PostgreSQL DDL.
|
||
- Path alias: import app modules via `~/*` (see `tsconfig.json`).
|
||
|
||
## Build, Test, and Development Commands
|
||
- `npm run dev` / `yarn dev`: Start local dev server on port 3000.
|
||
- `npm run build`: Production build (`.next`).
|
||
- `npm start`: Serve the built app.
|
||
- `npx next lint`: Run ESLint checks.
|
||
|
||
Environment: copy `.env.example` → `.env.local` and fill required keys (Stripe, Replicate webhook URL, Google OAuth, R2, Postgres). For first run, create tables from `sql/tables/*` in your database.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- TypeScript, React, Next.js App Router.
|
||
- Indentation: 2 spaces; prefer explicit types for public APIs.
|
||
- Components: PascalCase (`MyComponent.tsx`). Hooks: `useX.ts`.
|
||
- Modules/utilities: camelCase (`helpers.ts`), server modules under `src/servers`.
|
||
- Imports: prefer `~/...` alias for internal paths.
|
||
- Linting: ESLint (`extends: next/core-web-vitals`); run `npx next lint --fix` before pushing.
|
||
- Styles: TailwindCSS in components; keep class lists readable and deduplicated.
|
||
|
||
## Testing Guidelines
|
||
- No formal test framework is configured yet. Perform manual QA for:
|
||
- Auth flows, payment (Stripe test mode), image generation webhooks (use ngrok for local Replicate webhook), and locale pages.
|
||
- If adding automated tests, prefer Playwright for E2E and React Testing Library for components; place tests adjacent to sources.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Commits: short, imperative subject (e.g., "fix r2 region", "add stripe config"). Group related changes.
|
||
- PRs: clear description, linked issue, steps to validate (commands, URLs), and screenshots for UI changes.
|
||
- Keep changes scoped; update README and configs when behavior or env vars change. Never commit secrets.
|
||
|
||
## Security & Configuration Tips
|
||
- Store secrets only in `.env.*`. Rotate keys used for local testing. Verify webhook and cron/automation settings if deploying to Vercel.
|
||
|