71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
Basango — AGENTS.md
|
|
|
|
Scope
|
|
- Applies to the entire repository.
|
|
- Use these conventions when adding/modifying code, scripts, or docs.
|
|
|
|
Environment
|
|
- Node: >= 22
|
|
- Package manager: Bun `1.3.x`
|
|
- Task runner: Turborepo
|
|
- Lint/format: Biome
|
|
|
|
Workspace Layout
|
|
- `workspaces`: `apps/*` and `packages/*`.
|
|
- Internal packages use the `@basango/` scope and `workspace:*` versions.
|
|
- Avoid nested packages like `apps/**` or `packages/**`.
|
|
|
|
Packages
|
|
- `@basango/logger`: Pino wrapper. Prefer named import `import { logger } from "@basango/logger"`.
|
|
- `@basango/db`: Drizzle ORM for Postgres. Import via defined subpaths (`./client`, `./queries`, `./schema`, `./utils`).
|
|
- `@basango/ui`: Shared UI.
|
|
- `@basango/tsconfig`: Shared TS configs. Extend this in apps/packages.
|
|
|
|
Conventions
|
|
- ESM-only: set `"type": "module"` for packages that ship code.
|
|
- TypeScript everywhere. Use `extends: "@basango/tsconfig/base.json"` when possible.
|
|
- Prefer named exports in libraries. Avoid barrel files unless necessary.
|
|
- Use `workspace:*` for internal dependencies; do not hardcode versions.
|
|
- Keep changes minimal and localized; avoid cross-cutting refactors without discussion.
|
|
- When using tRPC in React, always compose `useQuery`/`useMutation` from TanStack with `trpc.*.queryOptions`/`mutationOptions` instead of calling `trpc.*.useQuery`/`useMutation` helpers directly (they are deprecated).
|
|
|
|
Tasks & Commands
|
|
- Install: `bun install` (run at repo root only).
|
|
- Dev: `bun run dev`.
|
|
- Build: `bun run build`.
|
|
- Typecheck: `bun run typecheck`.
|
|
- Lint/format: `bun run lint` or `bun run format`.
|
|
- Turbo filtering examples:
|
|
- `bunx turbo dev --filter=@basango/crawler`
|
|
- `bunx turbo build --filter=@basango/dashboard`
|
|
|
|
Adding a New Package
|
|
- Place apps in `apps/<name>`; libraries in `packages/<name>`.
|
|
- Use scoped name: `@basango/<name>` and set `"private": true` unless publishing.
|
|
- If a lib exposes multiple entrypoints, prefer `exports` map over `main`.
|
|
- Add dependencies with `bun add <pkg>` in the package directory; internal deps as `workspace:*`.
|
|
|
|
Logging
|
|
- Import logger as `import { logger } from "@basango/logger"` for consistency.
|
|
- Production logs are structured JSON; non-production uses `pino-pretty` transport.
|
|
|
|
Testing
|
|
- Use `vitest` where present. Add tests locally to the package being changed.
|
|
- Keep tests fast and focused. Do not introduce global test state.
|
|
|
|
Quality Gates
|
|
- `biome` formatting/linting is enforced. Run before committing.
|
|
- `manypkg check` runs as part of `bun run lint` to validate workspace correctness.
|
|
|
|
Commits & Hooks
|
|
- Conventional commits via Commitizen: `bunx cz`.
|
|
- Commitlint enforces message format. Husky hooks run on commit.
|
|
|
|
Gotchas
|
|
- Ensure `apps/*` and `packages/*` are the only workspace globs.
|
|
- Prefer named import for logger to avoid mixing default/named across files.
|
|
|
|
Contact Points
|
|
- Architecture overview: `docs/architecture.md`.
|
|
- Forms handling patterns: `docs/forms-handling.md`.
|