blob: 2893e8e2742eb881e00df6e7aa8812eb11e3530b (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
# Repository Guidelines
## Project Structure & Module Organization
- `src/`: application code.
- `components/`: UI components (e.g., `Flashcard/`, `tones/`, `ui/`).
- `actions/`: server actions (data fetching/mutations).
- `lib/`: shared types, helpers, config.
- `public/`: static assets served as-is.
- `dist/`: build output (generated).
- `waku.config.ts`: Waku app configuration.
- `bulkdata/`: project data assets.
Use absolute imports with `@/` (configured via tsconfig paths).
## Build, Test, and Development Commands
- Setup: `bun install` — install dependencies.
- Dev: `bunx --bun waku dev` — start the dev server with hot reload.
- Build: `bunx --bun waku build` — produce production build in `dist/`.
- Start: `bunx --bun waku start` — run the production server.
Example: `BUN_INSTALL_CACHE=1 bun install && bunx --bun waku dev`
## Coding Style & Naming Conventions
- Language: TypeScript + React 19, Tailwind CSS 4.
- Components: `.tsx`, PascalCase filenames (e.g., `ToneSelectorClient.tsx`).
- Utilities/types: camelCase files in `lib/`.
- Client components must begin with `"use client"` when using hooks/browser APIs.
- Prefer functional components and hooks; keep side-effects in `useEffect`.
- Follow existing Tailwind class patterns; co-locate small helpers with components.
## Testing Guidelines
- No formal test suite is enforced yet. If adding tests:
- Place unit tests next to source (`Component.test.tsx`) or under `src/__tests__/`.
- Use Bun’s test runner (`bun test`) or Vitest if introduced.
- Keep tests fast and focused; mock network/IO.
## Commit & Pull Request Guidelines
- Commit messages in history are informal; prefer concise, imperative subject lines.
- Recommended: Conventional Commits (e.g., `feat: add tone keyboard nav`).
- PRs should include:
- What/why summary and screenshots or clips for UI changes.
- Linked issues or TODO references.
- Scope-limited diffs and notes on breaking changes or migrations.
## Security & Configuration Tips
- Avoid committing secrets; prefer environment variables (configure via hosting env).
- Validate inputs in server actions under `src/actions/`.
- Keep client-only code behind `"use client"`; avoid leaking server internals to the browser.
## Architecture Notes
- App is a Waku + Bun React app. Pages and interactive views live under `src/components/**`. UI patterns like 3D flip (see `components/Flashcard/`) are shared across features (e.g., `tones/`). Reuse existing utilities and styles for consistency.
|
