TypeScript: what it does to JavaScript, and when to install it

The problem TypeScript solves, and the projects it does not fit

JavaScript has no type declarations. A function that expects an object with an id field will accept anything, and the failure surfaces at runtime, often in production, often far from the call site. TypeScript's answer is to add optional types on top of JavaScript and check them before the code runs. The README frames the target audience plainly: a language for application-scale JavaScript, with tools for large-scale JavaScript applications, for any browser, any host, any OS. The word doing the work there is scale. A fifty-line script does not benefit from an annotation layer you have to maintain alongside it. A codebase with several contributors, shared modules, and a build step already in place is where the trade pays off, because the compiler catches the class of mistake that code review and tests catch only sometimes. It is also worth being precise about what TypeScript is not. It is not a runtime. Types are erased during compilation; the emitted JavaScript has no type checks in it. If data arrives from an API, a form, or a config file, the compiler has no way to verify it at runtime, and the type you wrote is an assertion rather than a guarantee. Teams that treat annotations as validation end up with confident-looking code that fails exactly where they stopped looking.

How the compiler turns annotated source into plain JavaScript

The repository is organised around a compiler, not a framework. The top level holds tsc/ alongside packages/, tools/, and a Herebyfile.mjs, and the root package.json declares a private workspace named @typescript/repo with workspaces set to packages/*. The build, test, lint, and generate tasks are all routed through hereby, and the repository pins its own toolchain: typescript ^6.0.3 as a devDependency, Node >=22.18 in engines, and Volta entries for Node 24.20.0 and npm 11.17.0. That layout tells you something about the project's shape. It is a compiler with a large test corpus and a build pipeline, not a runtime library you import. The data flow is the familiar one: source files with type annotations go in, the checker validates them against declared types, and the emitter writes JavaScript that is described in the README as readable and standards-based. Because the output is ordinary JavaScript, the compiler can target whatever environment you already ship to, and nothing about your deployment changes. The checking happens at build time. That is the whole mechanism, and it is also the boundary: anything the compiler cannot see statically is outside its reach.

Installing TypeScript and running a first file

The README gives two install commands. The stable one is a local dev dependency, which is the right default because it pins the compiler version to the project rather than to whatever a developer happens to have globally:

npm install -D typescript

A nightly build is available under a dist-tag if you need unreleased fixes:

npm install -D typescript@next

The README does not describe a global install, and a project-local install is what the workspace layout implies. Once installed, the compiler binary is available through npx. A minimal setup is an init step that writes a config file, followed by a compile:

npx tsc --init
npx tsc

The first command generates a tsconfig.json in the current directory. The README does not document the individual compiler options, so read the generated file rather than assuming defaults; several of them change what gets emitted and where. For a quick check without touching the filesystem, the project points readers at the playground at typescriptlang.org/play, which runs the compiler in the browser. The documentation links from the README are the TypeScript in 5 minutes page and the programming handbook, both on typescriptlang.org, and those are the places to go for language syntax rather than this repository's README.

Where the type layer stops helping

The most common failure mode is not a compiler bug. It is a cast that silences the compiler without making the code correct. When a value arrives from outside the program, the annotation describes what you hope is there. Nothing checks it. The same applies to any boundary the compiler cannot follow: dynamic property access, data parsed from JSON, values injected at runtime by a framework. TypeScript's own documentation is explicit that types are erased, but it is easy to forget in practice, and the habit of reaching for a cast when the compiler complains converts a real signal into noise. There is a second cost that gets less attention. Annotations are code. They have to be updated when the underlying shape changes, and a stale annotation is worse than none, because it tells the next reader something false with the compiler's apparent authority. On a small script, or a one-off build utility, that maintenance bill exceeds the benefit. If your project has one author and no build step, adding a compiler to the pipeline buys you a config file and a watch process in exchange for mistakes you were already catching by running the code.

TypeScript against plain JavaScript, and against a runtime-typed language

The honest comparison is with JavaScript itself, because that is what TypeScript compiles to and what you would otherwise write. The difference is entirely in when errors appear. Plain JavaScript reports a bad property access when that line executes. TypeScript reports it when you compile, before the code has run, provided the value's type is knowable from the source. That is a real shift in feedback speed, and it is the reason the project exists. The cost is a build step and a set of annotations that must stay truthful. A second comparison people reach for is Python, and the difference in approach is worth stating precisely. Python checks types at runtime, and its optional type hints are not enforced by the interpreter. TypeScript's checker runs ahead of execution and rejects the program. Python's runs during execution and raises. Neither is strictly safer; they fail at different moments, and the one you want depends on whether you would rather block a build or catch an error in a running process. The README does not position TypeScript against Python, and the choice is usually made by the surrounding stack rather than by the type system.

Release lines, upgrade cost, and the Apache-2.0 licence

The repository shows two release lines in circulation: v7.0.2 published on 2026-08-20, and v6.0.3 published on 2026-04-16, with v6.0.2 before it on 2026-03-23. The last push to the repository was on 2026-08-20. That matters for planning because the compiler version is a project dependency, not an ambient tool, so an upgrade is a change to package.json that every contributor picks up on their next install. The repository's own devDependency sits on typescript ^6.0.3, which tells you the maintainers run the compiler against a 6.x line in their build. Nothing in the README describes a migration path between major versions, so treat a jump from 6.x to 7.x as something to verify against your own code rather than something the README will walk you through. The licence is Apache-2.0, stated in the repository's LICENSE.txt and in the root package.json. Apache-2.0 permits commercial and closed-source use and includes a patent grant, which is generally why projects in this position choose it over MIT. It also carries notice and attribution obligations, so if you redistribute the compiler or a modified copy, read the terms rather than assuming the permissive label covers everything. This is not legal advice.

Editorial conclusion

Adopt TypeScript on codebases where more than one person edits the same modules and the cost of a runtime type error is real; skip it for short scripts, build tooling that runs once, or a team that will let annotations drift out of sync with reality. Before committing, run npm install -D typescript, then npx tsc --init and check the generated tsconfig.json against your Node version, and confirm which release line you are pinning, since the repository shows v7.0.2 and v6.0.x as separate published versions.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes