The JavaScript application is growing and changes in one module keep breaking assumptions in another. TypeScript can make those contracts visible before release, provided the team does not mistake compile-time evidence for runtime validation.
TypeScript overlays static analysis and type syntax on JavaScript, then emits JavaScript for the chosen runtime. It can improve editor navigation, refactoring and API design across a substantial frontend or Node codebase. Its value depends on strictness, accurate dependency declarations and types that describe the real product instead of silencing the checker.
We adopt TypeScript to reduce the cost of change. More elaborate types are useful only when they make the code easier to use and maintain.
TypeScript pays back at boundaries that change together
A small script may gain little from a compiler and configuration. A product with shared models, many screens, API clients and several developers can use types to expose the impact of a field or function change across the codebase.
Discriminated unions express product states such as pending, failed and complete. Control-flow narrowing can then require each state to be handled. The narrowing handbook shows how never supports exhaustive checking when a new union member is introduced.
That benefit is strongest for owned contracts. A type generated or written from an API schema can align client use, while still needing runtime checks on the response. A broad Record<string, any> communicates little and lets change cost return.
We track outcomes such as refactor confidence, defect class and onboarding. The percentage of files renamed .ts tells us little.
TypeScript types are erased before customers run the code
The official introduction states that TypeScript preserves JavaScript runtime behaviour and erases types during compilation. An HTTP response, local-storage entry or message from another window does not become valid because a developer asserted its shape.
External data enters as unknown and is parsed or validated before becoming a domain type. Schema libraries can generate both runtime checks and static inference, or a shared OpenAPI or JSON Schema definition can produce client types. The source of truth should be named.
Type assertions are promises to the compiler, not conversions. Repeated as chains often show that the code lacks a trusted boundary. We isolate unavoidable assertions beside the evidence that makes them safe.
Browser and framework APIs can also return nullable or mutable values the application must handle. Static checking narrows possible mistakes; it does not remove tests or monitoring.
Strictness is a product policy rather than a switch to fear
The strict family enables stronger checking around nulls, functions, properties and related behaviour. New projects normally benefit from a strict baseline. An old JavaScript application may need staged adoption to avoid thousands of unrelated errors in one release.
We commit the tsconfig and document inherited configurations. Changing strictNullChecks, indexed access or optional-property semantics can reveal real bugs and require model changes. It deserves its own focused migration instead of being folded into a tool upgrade.
any deliberately opts out and spreads through callers. We prefer unknown at uncertain boundaries because it requires narrowing. A small, explained any at a legacy library edge is more honest than a complicated incorrect declaration.
Generated files and tests can use different settings where justified, but production source should not contain arbitrary local escape hatches. Type errors fail CI.
Type sophistication should reduce caller complexity
TypeScript’s structural and conditional type system can model rich JavaScript patterns. Library authors may need generics that preserve relationships between inputs and outputs. Application code often needs fewer tricks.
If an error message requires a specialist to decode or editor performance suffers, the abstraction may be saving lines at the expense of change. We favour named domain types, straightforward generics and overloads whose runtime implementation is equally clear.
Types should prevent invalid states where practical without attempting to reproduce every business rule in the compiler. Price thresholds, permissions and current inventory remain runtime decisions.
Public types receive examples and tests. A clever utility used once is replaced with explicit code when that code is easier for the next maintainer.
Declaration files are a trust boundary around JavaScript
TypeScript understands JavaScript libraries through bundled declarations, generated declarations or community packages such as DefinitelyTyped. Those types can be incomplete or out of step with the installed runtime version.
We choose libraries with maintained declarations and test important runtime behaviour. A declaration that claims a value cannot be null does not override the library’s actual response. Module augmentation and local fixes are documented and removed when upstream catches up.
When publishing an internal package, its declaration output is part of the API. Accidental exported types can tie consumers to private dependencies. API review covers emitted .d.ts files and semantic versioning alongside JavaScript output.
The TypeScript declaration-file guidance helps authors describe existing JavaScript, but consumers retain responsibility for version alignment.
Module settings must match the runtime and bundler
TypeScript checks and emits modules according to compiler configuration, while Node, browsers, package metadata and bundlers decide how modules load at runtime. A build can type-check and still fail because ESM, CommonJS, paths or extensions are misaligned.
We start from the actual runtime and the framework or build tool’s documented settings. Path aliases require runtime or bundler support; TypeScript resolution alone does not rewrite every import.
The release runs the emitted or bundled artefact in a production-style environment. Tests that execute source through a different transformer can hide packaging errors.
Source maps are produced and protected so production stack traces map to reviewed TypeScript without exposing source unnecessarily. Node and browser targets receive separate configurations when their globals and module rules differ.
Large TypeScript builds need explicit project boundaries
One huge compiler project can consume memory and slow editor feedback. TypeScript project references split programs into buildable pieces, expose declaration boundaries and support build mode.
They are useful when the repository has real package ownership and dependency direction. Splitting an application into dozens of projects before measurement can add configuration and declaration churn with little benefit.
We measure clean build, incremental build and editor response, then fix the dominant source. Large inferred unions, duplicated generated types and broad includes can be more important than repository size.
Compiler and package updates are made regularly with diagnostics reviewed. Staying many releases behind lets deprecated settings and dependency constraints accumulate into a larger migration.
JavaScript migration can be staged without a rewrite
TypeScript can check JavaScript files, read JSDoc and allow a mixed project. The official JavaScript project guide describes levels from inference through checked JavaScript to strict TypeScript.
We start at active, high-change modules and external boundaries. Tests preserve behaviour while types are added. Renaming every file before improving contracts creates a large diff with limited product evidence.
Migration rules prevent backsliding: new modules meet the target strictness, escape-hatch counts are visible and completed folders stop accepting unchecked JavaScript. Legacy areas can remain until they change for a reason.
A mixed codebase with clear boundaries can be healthier than all-TypeScript source full of any and assertions.
Questions to answer before adopting TypeScript
- “Which changes currently break hidden contracts?” Target the real maintenance cost.
- “Where does untrusted runtime data become a domain type?” Add validation there.
- “Which strictness settings are the target and migration path?” Keep them in source.
- “How much
anyand assertion debt will be accepted?” Make escape hatches reviewable. - “Do dependency declarations match the installed JavaScript?” Test critical edges.
- “Which runtime and module system receives the output?” Run the release artefact.
- “What build or editor threshold would trigger project references?” Measure before splitting.
When TypeScript is a sound investment
Choose TypeScript for maintained JavaScript applications with shared models, several contributors and enough change that compiler-checked contracts reduce risk. It is especially effective across React, Vue and Node products using a common JavaScript ecosystem.
The decision is complete when strictness, runtime validation and module output are explicit. Types should make the code easier for the product team to change.
When TypeScript adds ceremony without enough return
Keep plain JavaScript or checked JSDoc for small, stable scripts where distribution and simplicity matter more than cross-module refactoring. The TypeScript language service can still provide useful inference.
Do not treat TypeScript as an API firewall. Validate network, storage and user data at runtime regardless of how precise the client interface appears.
And simplify types that are harder to understand than the business rule. Compile-time power is valuable when it removes uncertainty for maintainers.
Use TypeScript to make change safer, with runtime truth kept at the boundary.
I choose TypeScript for JavaScript products whose contracts and refactors have become expensive to hold in people's heads. I want strictness and runtime validation named, not a codebase that asserts every uncertain value into compliance. If the types make callers and changes clearer, they are doing useful work.
Alexander De Sousa · Founder, Digital Royalty · LinkedIn
What TypeScript can prove and what remains runtime responsibility
TypeScript checks JavaScript contracts before execution. External data, library behaviour, module loading, emitted code and production errors remain runtime facts.
The TypeScript commitment in six decisions
- Best fit
- Maintained JavaScript applications with shared domain contracts, several contributors and enough change to repay static analysis.
- Product effect
- Earlier feedback on incompatible changes and stronger editor navigation, without runtime protection from malformed external values.
- Adoption cost
- Low for a new strict project; moderate for staged JavaScript migration; higher where declarations, module systems and complex generics are already inconsistent.
- Ongoing owner
- Frontend or Node teams responsible for compiler configuration, strictness, declarations, runtime schemas, build output and regular upgrades.
- Exit cost
- Low at runtime because output is JavaScript; moderate in development when source, tooling and public declarations rely on TypeScript features.
- Proof required
- Strict CI type-check, invalid API response test, production module execution, dependency declaration check and measured editor or build performance.
Typing routes to compare for an existing JavaScript product
-
JavaScript with inference and tests
Right when: The code is small, stable and locally understood and a compiler configuration would add little change or navigation value.
Watch for: Hidden object contracts become harder to refactor as modules and contributors grow.
-
Checked JavaScript with JSDoc
Right when: Existing JavaScript needs editor and type feedback without changing its source extension or distribution process.
Watch for: Complex types can become verbose in comments, and project strictness still needs an agreed configuration.
-
Strict TypeScript
Right when: A maintained product benefits from compiler-enforced contracts and the team can validate data at runtime.
Watch for: Avoid `any` and assertions that produce nominal adoption without useful checking.
-
Schema-led contracts with generated types
Right when: Several clients and services need one versioned runtime contract and generated TypeScript can reduce duplicated model declarations.
Watch for: Generated types need runtime validation, source control and a reviewable API change process.
Research behind this TypeScript position
-
Official language purpose
TypeScript Handbook introduction
Defines TypeScript as a static checker for JavaScript programs, keeping its value tied to pre-execution feedback.
-
Official runtime model
TypeScript for the new programmer
States that types are erased and JavaScript runtime behaviour is preserved, making runtime validation a separate responsibility.
-
Official control-flow types
TypeScript narrowing
Shows control-flow analysis, type guards and exhaustive union checks used to make product states explicit.
-
Official configuration
TypeScript strict option
Defines the family of stronger checking options that turn TypeScript adoption into a documented safety policy.
-
Official scaling guidance
TypeScript project references
Provides buildable declaration boundaries for large repositories and explains the associated compiler mode.
-
Official migration guidance
JavaScript projects using TypeScript
Describes staged checking from inference and JSDoc through strict TypeScript, supporting migration without an all-file rewrite.
-
Practitioner question
Stack Overflow: validating a TypeScript interface at runtime
The recurring question exposes confusion between static interfaces and runtime data; the language's erased-type model provides the answer.
-
Developer survey
State of JavaScript 2025 TypeScript findings
Provides broad self-reported adoption context. It does not establish strictness, runtime validation or product fit for one codebase.
Tell us what you need
A few quick questions, then a straight answer from a real person — usually within a few hours.
What happens next
- 1 We reply A real person reads your answers and gets back to you, usually within a few hours.
- 2 Questions or a short call If anything isn't clear, we ask by email or book a short call. Before any call we audit your website and make the quick fixes it finds, free.
- 3 Your fixed quote A clear, fixed price in writing, within 48 hours of any call. There is no obligation to go ahead.
Tell us what you're working on
Whether it's a new site, a platform, or a process that shouldn't be manual any more — we'll tell you honestly if we can help.