|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | + |
| 5 | +- Source: `src/` with: |
| 6 | + - `pages/` (Astro routes and API endpoints: `.astro`, `*.ts` like `image.png.ts`). |
| 7 | + - `components/` (client/server React `.tsx` and `.astro`). |
| 8 | + - `layouts/`, `styles/`, `domains/` (domain logic), `routes/` (route helpers), and `content/` (MDX content). |
| 9 | +- Public assets: `public/` (served at `/`, e.g., `/background.png`). Build output: `dist/`. |
| 10 | +- Content collections: configured in `src/content.config.ts` using Astro Content. Collections include `creators`, `games`, `assets`, `resources`, and `docs`, with content under `src/content/<collection>/`. |
| 11 | + |
| 12 | +## Build & Development |
| 13 | + |
| 14 | +- `bun install`: install dependencies. |
| 15 | +- `bun run dev`: start local dev server (defaults to `http://localhost:4321`). |
| 16 | +- `bun run build`: production build to `dist/` (runs `astro build`). |
| 17 | +- `bun run preview`: serve the built site locally. |
| 18 | +- `bun run check`: Astro/TS diagnostics (type and config checks). |
| 19 | +- Deployment: Netlify adapter is configured in `astro.config.mjs`; scripts `alpha`/`prod` use the Netlify CLI. |
| 20 | + |
| 21 | +## Style & Syntax |
| 22 | + |
| 23 | +- Prettier + Tailwind plugin enforce formatting. Use PascalCase for components, camelCase for functions, UPPER_SNAKE for constants; filenames generally kebab-case. Dynamic route params use descriptive camelCase (e.g., `[creatorSlug]`). |
| 24 | +- Prefer `function` declarations/expressions for non-passed functions (route handlers, utilities). Use arrow functions when passing (React event handlers, callbacks). Prefer `type` over `interface`. |
| 25 | +- For non-render functions, accept a single `params` object (no destructuring); favor readable, multi-line steps over deep chains. |
| 26 | +- Curly braces: always include `{}` for control statements (`if/else`, `for`, `while`, `do`, `switch`, and non-trivial arrow bodies). Avoid single-line or inline `if` without braces. |
| 27 | + |
| 28 | +## Components & UI |
| 29 | + |
| 30 | +- Single `props` param: components accept a single `props` parameter. Do not destructure in the signature. |
| 31 | +- Inline prop types: annotate the parameter inline; avoid exporting standalone `*Props` types. |
| 32 | +- Defaults rule: create local defaults from `props`, e.g., `const size = props.size ?? "2"`. |
| 33 | +- Spreading rule: if spreading HTML attributes, destructure inside the body to obtain `...rest`; otherwise avoid destructuring `props`. |
| 34 | +- Order: function declaration and defaults → React state hooks → derived consts → effects (name `useEffect` callbacks) → event handlers (`function handleClick() {}`) → return JSX → sub-render helpers at bottom. |
| 35 | +- React hooks import: import hooks directly (`import { useState, useEffect } from "react"`), do not call them off the React namespace (avoid `React.useEffect`, `React.useState`). |
| 36 | +- Styling: prefer Tailwind utilities; use `cn(...)`/`twMerge(...)` for class merging when needed. |
| 37 | +- Sub-render helpers: when extracting tiny render fragments inside a component, use plain functions scoped to that component and name them `renderThing(params)`. These are not React components and should not use hooks; they return JSX and are called like `renderThing({ ... })`. |
| 38 | +- Components vs helpers: anything used as `<Thing />` is a real React component and must accept a single `props` parameter (not `params`). Reserve `params` objects for non-React functions and sub-render helpers. |
| 39 | +- Render helpers placement: do not declare render helpers inline inside JSX. Define them as `function` declarations after the component’s return block. Call them inside JSX like `renderThing({ ... })`. |
| 40 | + |
| 41 | +## Testing & PRs |
| 42 | + |
| 43 | +- Run `bun run check` to check for errors/warnings. |
| 44 | +- Commits: conventional prefixes (`feat:`, `fix:`, `chore:`). PRs: summary, linked issues, screenshots for UI, and notes on env/migrations. |
0 commit comments