Repo conventions

Bun-based starter for web projects built with coding agents. License: The Unlicense.

Invoke related skills

Workspace layout

• apps/* — applications (none yet)
• packages/* — shared libraries (none yet)
• scripts/ — repository scripts and their tests
• src/styles.css — Tailwind CSS entry (@import "tailwindcss"; configuration lives in CSS, there is no tailwind.config.js)
• repos/* — read-only reference clones (git-ignored, listed in repos.json). Never edit or import from them

Do not invent new apps or packages unless asked.

Tooling (Bun only)

Do not introduce npm, yarn, or pnpm.

bun install
bun run verify         # pre-commit gates in parallel
bun run ci             # verify + Tailwind build
bun run fmt / fmt:check          # oxfmt
bun run lint / lint:fix          # oxlint
bun run typecheck                # bun check
bun run test                     # bun test
bun run md:check / md:fmt / md:fmt:check   # rumdl
bun run css:build / css:watch    # Tailwind CLI → dist/styles.css
bun run storybook / storybook:build
bun run prd                      # build CSS, serve dist/ over HTTPS
bun run serve:https              # serve SERVE_DIR (default dist) over HTTPS
bun run certs / certs:clean      # local HTTPS certificate in .certs/

• Root workspaces.catalog pins shared deps ("catalog:"). Workspace-specific deps stay in that package's package.json.
• New scripts use Bun-native APIs (Bun.file, Bun.write, Bun.$, Bun.spawn / Bun.spawnSync, Bun.Glob, import.meta.dir, Bun.env).
• Prefer local Bun types docs under node_modules/.bun/bun-types@*/…/docs/ over the network.
• Do not add ESLint, Prettier, or Playwright/Puppeteer. Formatting and linting are OXC (oxfmt, oxlint).

Type checking

Type checking is bun check (it embeds TypeScript), not tsc. There is no typescript package and none may be added. A root package script named check would shadow bun check; use bun --check then. Extend the root tsconfig.json. exactOptionalPropertyTypes is on.

Local HTTPS

scripts/certs.ts makes a certificate in .certs/ (git-ignored, never commit the key) with mkcert when installed, else a self-signed openssl one. scripts/serve-https.ts serves a build directory with it. Arch Linux only for now. Details in docs/local-https.md.

Git hooks (Lefthook)

bun install runs scripts/install-git-hooks.ts (prepare) so Lefthook hooks are in .git/hooks. It skips when CI=true.

• pre-commit: bun run verify (format is checked, not fixed — run bun run fmt / md:fmt, then stage)
• commit-msg: Conventional Commits via scripts/check-commit-subject.ts
• Never bypass hooks (--no-verify, LEFTHOOK=0)

Reference repositories

bun install / bun run vendor shallow-clones repos.json into repos/<name>. Skipped when CI=true or SKIP_VENDORED_REPOS=1. Read library source and tests there before relying on behaviour.

Commits

• Atomic commits; Conventional Commits (feat:, fix:, docs:, chore:, refactor:, test:)
• Commit only when the user asks or repo policy authorizes it

Source changes

Do not change unrelated source. Match existing style. Prefer small, focused edits.