Skip to content

CLAUDE.md

Latest commit

 

History

History
34 lines (22 loc) · 2.63 KB

CLAUDE.md

File metadata and controls

34 lines (22 loc) · 2.63 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this directory is

A notes/reference directory, not a source code repository. Actual TypeScript and frontend projects live in other directories on disk. There is nothing to build, test, or lint here — just markdown files maintained by hand.

Files

  • MAC.md — one-time macOS setup playbook for a TypeScript/frontend dev machine (mise, pnpm, Node LTS, global config, shell env, Claude permissions). Steps are numbered and meant to be executable top-to-bottom on a fresh Mac.
  • PROJECT.md — per-project TS best practices once the machine is set up (src/ layout, package.json, ESLint flat config, Prettier, Vitest, tsc, logging, error handling) plus a frontend chapter (Vite + React + Tailwind + shadcn/ui) and copy-paste templates. Referred to when bootstrapping any new TS/frontend project anywhere on disk.

MAC.md is the machine layer; PROJECT.md is the next layer up. PROJECT.md links back to MAC.md for install steps and does not duplicate them.

Editing conventions

  • MAC.md documents universal fresh-machine setup only. Don't add one-off repairs for this specific machine's prior state. A reader on a clean Mac wouldn't need them. Perform one-offs in execution but leave them out of the doc.
  • For reference/playbook docs, the doc is the plan. When asked to write or update MAC.md / PROJECT.md, write the final content directly to the target file — don't produce a separate meta-plan about what the doc will contain.

Stack the docs prescribe

pnpm (deps) · ESLint flat config + Prettier (lint+format) · Vitest (tests) · TypeScript (tsc --noEmit) · React + Vite (frontend) · Tailwind v4 + shadcn/ui (styling+components) · pino (Node services). Node LTS is the global default (mise-managed). src/ layout, package.json as single source of truth, pnpm-lock.yaml committed, ESM only.

TypeScript / pnpm conventions

  • All TS work uses pnpm. Never run npm install -g.
  • Start projects with pnpm init then add deps as needed: pnpm add -D typescript tsx vitest @types/node.
  • Add deps with pnpm add <pkg> / pnpm add -D <pkg>. Remove with pnpm remove <pkg>.
  • Run scripts with pnpm <script>. One-off TS files: pnpm exec tsx file.ts.
  • After pulling: pnpm install (dev) or pnpm install --frozen-lockfile (CI).
  • Per-project Node version: commit .nvmrc (e.g. 22). mise reads it natively. Global default = LTS.
  • Commit: package.json, pnpm-lock.yaml, .nvmrc, tsconfig.json. Gitignore: node_modules/, dist/.
  • For global CLI tools, prefer mise use --global <tool> over npm i -g.