Incremental Adoption of TypeScript to Improve Safety & Onboarding

[flyblackbox]

Problem / Motivation

Micah pointed out that the codebase is 100 % JavaScript and lacks static type safety:

• We’re already modernizing dependencies (see PR Code Cleanup and Package Updates #146) and adding Docker dev DBs—this is a natural time to tighten type guarantees.

Proposal — Incremental TypeScript Adoption

1. Tooling – add typescript, @types/node, @types/react/**, etc. Commit a baseline tsconfig.json (strict-ish, but not blocking migration).
2. Transpile path – use ts-node-dev for server scripts; on the client, migrate CRA → Vite (or keep CRA with react-scripts’ TS template).
3. Gradual opt-in – rename high-value files to .ts/.tsx (start with src/utils, shared hooks, & API route handlers).
4. Type linting – extend ESLint with @typescript-eslint/*; CI fails on type errors (npm run typecheck).
5. Docs – update CONTRIBUTING.md and README with setup + “How to convert a JS file to TS”.

Acceptance Criteria

• typescript & type deps in package.json
• Root tsconfig.json committed
• npm run typecheck script and CI job added
• ≥ 20 % of codebase (or src/utils, src/hooks, src/components/common) converted with no any suppressions
• ESLint passes locally & in CI
• New doc: docs/ts-migration.md (step-by-step guide)

Suggested Task Breakdown

Step	Owner	Details	ETA
1	any	Add TS deps & tsconfig.json	1 h
2	any	Add ESLint/Prettier TS rules	1 h
3	any	Convert src/utils/*	2–3 h
4	any	Convert src/hooks/* & one sample page	3–4 h
5	any	Add npm run typecheck to CI	1 h
6	any	Update docs & PR template	1 h

Risks / Mitigations

• Large diffs → keep PRs < 300 LOC and scoped to one folder.
• Legacy bugs → run unit tests after each migration slice.
• Contributor friction → document npx tsc --noEmit in PR checklist.

References

• Hacknight Reimplement previous login #4 with @niamao & @micah.shute (2025-06-01) re: modernizing the stack
• PR Code Cleanup and Package Updates #146 – Package & cleanup upgrade (blocked until merged)