TypeScript Toolchain
Mandate
TypeScript and Python are the default languages for AI-assisted development because they have the strongest library and agent ecosystem support.
Language priority:
- Default to TypeScript for product and full-stack development.
- Use Python for the cases listed in Python Toolchain.
- Reserve Go and Rust for performance-critical or systems work; both require a clear reason, user approval, and a project ADR. See Go and Rust.
For framework selection, see Frontend Framework: Vite vs Next.js.
Version Policy
Use the latest stable TypeScript and Node.js on the Active LTS line.
As of 2026-08, the Active LTS line is Node.js 24 (EOL 2028-04); Node.js 22 is in maintenance (EOL 2027-04), and Node.js 26 is the Current line until 2026-10. Never target the Current line; upgrade the Node major only after the new LTS line has settled.
Models generate code from training data, so mainstream, thoroughly validated versions cause fewer errors in AI-assisted development. Prefer them over marginal gains. The principle lives in Core Engineering Principles.
Pin the Node.js version in the project's mise configuration; pin the TypeScript version through the pnpm lockfile — never rely on globally installed versions of either.
pnpm
Use pnpm. This applies to both standard Node.js projects and monorepos.
When pinning pnpm in mise.toml, use the latest version and check it via mise (mise latest pnpm). Note that pnpm latest in npm is 11, but the actual latest version is 12.
When external documentation provides npm or yarn commands, adapt them to pnpm rather than introducing another package manager.
The project lockfile must remain consistent with pnpm.
Rejected Alternatives
Do not use:
- npm
- yarn
oxlint
oxlint is the standard TypeScript / JavaScript linter.
When a framework, template, or library recommends ESLint:
- Identify which ESLint rules or plugins it relies on.
- Determine whether the required functionality is supported by oxlint.
- Use the oxlint equivalent whenever possible.
- Do not keep ESLint merely because it was generated by a template.
Use the latest stable oxlint version unless a concrete compatibility issue requires otherwise.
Rule Configuration
Configure oxlint deliberately: enable the rules and plugins that match where the code runs, not just the defaults. Do not leave useful checks off just because a starter template omitted them.
For Node.js code, enable the node plugin in .oxlintrc.json and turn on its rules — including guards against legacy CommonJS patterns — while skipping rules that conflict with the project's purpose (for example, keep no-sync off in CLIs that intentionally read files synchronously).
Type-Aware and Type Checking Rules
Enable oxlint's TypeScript type-aware linting and type checking when appropriate.
Install oxlint-tsgolint alongside a current oxlint and enable options.typeAware and options.typeCheck in the root .oxlintrc.json (typeCheck is experimental as of 2026-08).
Follow the current official oxlint docs rather than copying old configs, and do not add ESLint just for type-aware rules when oxlint covers them.
Rejected Alternatives
Do not use ESLint as the default linting system.
oxfmt
oxfmt is the standard formatter for TypeScript / JavaScript projects.
Use the latest stable oxfmt version unless a concrete compatibility problem prevents it.
Do not run multiple competing formatters over the same source files.
Rejected Alternatives
Do not use Prettier.
tsconfig Baseline
Start every project from a strict tsconfig baseline:
"strict": true— the strictness base; do not disable individual strict flags without an ADR-level reason."noUncheckedIndexedAccess": true— indexed access yieldsT | undefined, forcing the undefined case to be handled."verbatimModuleSyntax": true— type-only imports must useimport type, preventing accidental runtime imports."isolatedModules": true— every file must compile independently, matching how bundlers and transpilers actually process the code.- ESM only. Applications use
"module": "ESNext"with"moduleResolution": "Bundler"; Node libraries use"module": "NodeNext"with"moduleResolution": "NodeNext". - Applications do not emit with tsc: set
"noEmit": trueand let the bundler produce the output.
Baseline example:
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"verbatimModuleSyntax": true,
"isolatedModules": true,
"module": "ESNext",
"moduleResolution": "Bundler",
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"noEmit": true,
},
}
Language Usage Rules
- Prefer
unknownoveranywhen a value's type is not yet known, and narrow it before use. Reserveanyfor genuinely dynamic interop, with a comment justifying it. - Do not use the non-null assertion operator (
!) without a comment explaining why the value cannot be null or undefined at that point. - Declare explicit return types on exported functions.
- Model state with discriminated unions instead of groups of booleans.
- Validate configuration objects with
satisfies: errors surface at the definition while literal types are preserved. - Apply
as constto literal tables so element types stay narrow. - Use union types or
constobjects instead ofenum. - Do not leave promises floating:
awaitthem, or discard deliberately withvoidplus a comment stating why the result is ignored. - Throw
Errorsubclasses; never throw strings or plain objects.
Project Conventions
- Keep application source under
src/and expose entry points throughpackage.json. - Name files in kebab-case (
user-profile-card.tsx), values in camelCase, and types, components, and classes in PascalCase. - Avoid barrel files (an
index.tsre-exporting a whole directory); import directly from the defining module. Barrels hurt tree-shaking and invite import cycles.