Skip to main content

Style Guide

TypeScript​

Core app code lives in platform/app, platform/components, platform/features, and platform/lib. These directories should stay TypeScript-only: use .ts for logic and .tsx for React components.

Maintained data and build scripts should also use TypeScript when they contain meaningful business logic or mirror runtime behavior.

JavaScript exceptions are intentionally narrow:

  • framework config files where the ecosystem default is still JavaScript, such as eslint.config.mjs and postcss.config.mjs
  • copied vendor artifacts, such as platform/public/pdf.worker.min.mjs
  • tiny legacy one-off scripts until they are touched for real work

Data Boundaries​

External data should be typed at the edge. CSV rows, NDJSON tuples, JSON files, network responses, and browser storage values should be parsed into local types before application code relies on them.

Avoid carrying broad any types through the app. If the input is unknown, use unknown, validate or narrow it, then pass a typed value forward.

Linting​

Run linting from the platform package:

cd platform
npm run lint

The linter enforces that core app directories do not receive JavaScript files. It deliberately allows the small config and vendor exceptions above.

Codex Guidance​

Codex reads platform/AGENTS.md, which mirrors the TypeScript rules here. Keep that file updated when these conventions change so automated edits follow the same standards as human edits.