2026-03-18 TypeScript Adoption Plan

Goal

Adopt TypeScript incrementally across Lantern to improve safety at app/service boundaries, reduce runtime regressions, and keep delivery velocity high.

Current State (Verified)

• No active TypeScript source files (.ts, .tsx, .mts, .cts) found.
• No tsconfig*.json currently present.
• Tooling is partially TS-ready:
  • Vitest includes TS/TSX patterns in web/admin test globs.
  • Storybook story globs include ts|tsx.
  • Header validation scripts already account for ts|tsx.
• Main implementation remains JS/JSX (apps/web, apps/admin, services/*, packages/*).

Recommendation

Proceed with a phased migration (hybrid JS + TS), not a big-bang rewrite.

Why:

• Low tooling friction (some TS-ready config already exists).
• High payoff in shared contracts and backend/API boundaries.
• Minimal disruption if introduced in layers.

Scope

In scope:

• Add TypeScript compiler + baseline config.
• Enable type-checking in CI.
• Introduce typed shared contracts first.
• Migrate high-risk/high-churn modules incrementally.

Out of scope (initially):

• Full repo conversion in one pass.
• Strict mode everywhere on day one.
• Rewriting stable/low-risk modules just for extension parity.

Phased Rollout

Phase 0: Baseline Setup (1 PR)

Deliverables:

• Add typescript and essential type packages.
• Add root tsconfig.base.json.
• Add workspace tsconfigs for web/admin/services/packages as needed.
• Keep JS running via allowJs: true.
• Enable checks with checkJs: true where valuable.
• Add typecheck scripts and wire into validation.

Success criteria:

• typecheck runs in CI without changing runtime behavior.
• Existing build/test/lint pipelines remain green.

Phase 1: Shared Contracts First (1–2 PRs)

Targets:

• packages/shared (constants, service registry contracts, rate limit schema).
• Introduce explicit interfaces/types for:
  • API services registry entries.
  • CORS origin sets.
  • Rate limit presets.

Success criteria:

• Shared package exports typed contracts consumed by apps/services.
• No regressions in imports or runtime execution.

Phase 2: Backend/API Boundary Hardening (2–4 PRs)

Targets:

• Cloud Run services with HTTP payload boundaries first:
  • services/api/auth
  • services/api/analytics
  • services/api/venues
  • services/api/lanterns

Focus:

• Request/response DTO typing.
• Auth/session payload typing.
• Firestore document shape typing at read/write boundaries.
• Runtime validation preserved (types do not replace validation).

Success criteria:

• Boundary modules typed.
• Reduced “shape mismatch” bugs in integration tests.

Phase 3: Frontend High-Value Modules (2–4 PRs)

Targets:

• apps/web/src/lib/* service modules first.
• Shared component props in frequently reused UI primitives.
• State and event payload typing where bugs have historically occurred.

Success criteria:

• Core service modules typed.
• Component prop contracts documented by TS.
• No drop in test coverage threshold compliance.

Phase 4: Tighten Rules (optional)

• Incrementally enable stricter compiler flags by folder/package.
• Convert remaining opportunistically touched files.
• Keep mixed JS/TS support until migration ROI declines.

Proposed Compiler Strategy

Initial defaults:

• allowJs: true
• checkJs: true (can be selective)
• noEmit: true (build still via existing Vite/toolchain)
• skipLibCheck: true
• strict: false initially, then ratchet up package-by-package

Ratcheting sequence:

1. noImplicitAny
2. strictNullChecks
3. broader strict

CI & Quality Gates

Add/adjust:

• typecheck command per workspace.
• Root validation pipeline includes typecheck.
• Keep existing lint/tests/coverage unchanged during rollout.

Guardrails:

• No deployment/process changes.
• No branch strategy changes.
• Avoid coupling migration PRs with feature PRs.

Risks & Mitigations

Risk: migration churn slows feature delivery
Mitigation: small PRs, boundary-first prioritization, mixed JS/TS period

Risk: false confidence from types alone
Mitigation: keep runtime validation for external inputs

Risk: CI noise from strictness too early
Mitigation: start permissive, ratchet strictness gradually

Suggested First Conversion Targets

1. Shared service registry and related config contracts (packages/shared/services).
2. API boundary handlers in services/api/auth.
3. Shared utility modules with repeated cross-project usage.

Definition of Done (Initial Adoption)

• TypeScript installed and configured at workspace level.
• Typecheck runs in CI and passes.
• packages/shared exports typed contracts used by at least one app and one service.
• At least one backend service has typed request/response boundaries.
• No runtime or deployment regressions.

Execution Notes

• Keep PRs focused and reversible.
• Prefer converting touched files over mass rename sweeps.
• Document migration decisions in the PR body and changelog after completion.