TypeScript Compatibility
Nova uses TypeScript 6 as one shared compiler baseline for presets, command-line utilities, declaration tests, and generated project templates.
Supported Versions
| TypeScript version | Status | Project guidance |
|---|---|---|
6.0.3 | Supported | Pin this exact version in every workspace that directly declares TypeScript. |
Other 6.x | Compatible | Nova's package peer range accepts ^6, but exact project pins prevent drift. |
5.x | Unsupported | Upgrade the project and its TSConfig files together instead of mixing baselines. |
7.x | Unsupported | Nova will add support only after its compiler-backed features are compatible. |
Nova intentionally supports one complete TypeScript major at a time. This keeps the preset behavior, diagnostics, and compiler API usage consistent across every Nova-managed workspace.
Why Nova Depends on the Compiler Version
Most TSConfig presets are JSON, but several Nova features use TypeScript's compiler API directly:
nova utility type-checkparses a project and reports project-owned diagnostics.nova utility transpileparses a project and emits compiled output.- The type declaration Vitest suite inspects TypeScript source and declaration files.
- Nova's own declaration generator and validation tooling inspect TypeScript syntax.
TypeScript 6 preserves the compiler API these features use. TypeScript 7 does not yet provide the compatible API surface Nova needs, so installing the latest unpinned TypeScript release is not supported.
Upgrade from TypeScript 5
Update the package version and TSConfig wiring together.
In TypeScript 6, paths entries resolve relative to the TSConfig file when baseUrl is absent. Remove only the TypeScript compilerOptions.baseUrl setting. A Docusaurus site's top-level baseUrl setting controls deployed URLs and is unrelated.
TypeScript 6 Configuration Changes
| Setting | Nova guidance |
|---|---|
baseUrl | Remove the compiler option. Keep paths for aliases. |
rootDir | Set it explicitly for projects that emit files, so output layout does not depend on inferred roots. |
strict | Keep it explicit through dx-strict or a framework's strict base config. |
types | List every ambient type package intentionally, or write [] when the project needs none. |
noUncheckedSideEffectImports | Keep it explicit through dx-strict so unresolved side-effect imports fail consistently. |
module and target | Keep using Nova presets so TypeScript's changing defaults do not alter the project's runtime output. |
Verification
After updating the version and configs, reinstall dependencies so the lockfile records TypeScript 6, then run the project checks and build from the monorepo root.
npm install
npm run check
npm run build
Related
- Review local TSConfig wiring in TSConfig Best Practices.
- Use Type Check for project-owned diagnostics.
- Use Transpile when TypeScript should emit the project output.