ts-morph

ts-morph wraps the raw TypeScript Compiler API in an object-oriented, discoverable layer, exposing a Project object that loads source files and lets you navigate, query, and programmatically modify TypeScript/JavaScript ASTs without wrestling with the compiler’s low-level node factories directly. Common tasks — adding an import, renaming a symbol project-wide, extracting an interface, or rewriting call expressions — become a handful of chainable method calls instead of manual AST construction and printer plumbing.

Because it sits directly on top of the real TypeScript compiler, ts-morph gets full type-checking and language-service accuracy for free, which is why it’s a common backbone for codemods, custom linters, doc generators, and code-generation tooling in TypeScript projects.

What You Get

• A Project API for loading TypeScript/JavaScript files from disk, tsconfig.json, or an in-memory virtual file system
• Wrapped, chainable AST node classes (SourceFile, ClassDeclaration, InterfaceDeclaration, etc.) with discoverable getters and mutators
• Project-wide symbol renaming and reference finding backed by the real TypeScript language service
• Code generation helpers for adding/removing imports, classes, methods, and properties without manual AST/printer code
• A ts-morph.d.ts-backed structure API for describing code declaratively via plain objects instead of imperative builder calls

Common Use Cases

• Writing codemods that rewrite deprecated API usage across a large TypeScript codebase
• Generating TypeScript declaration files, client SDKs, or boilerplate from schemas or other source-of-truth definitions
• Building custom static-analysis tools or linters that need type-checked AST traversal
• Automating large-scale refactors (renaming exports, extracting interfaces, restructuring modules) safely across many files

Under The Hood

Architecture - The packages/ts-morph package’s src/compiler directory wraps every relevant TypeScript compiler AST node in a corresponding ts-morph class that holds a reference to the underlying ts.Node and the owning Project’s ts.Program/language service, so navigation methods (getParent(), getChildren()) and mutation methods (.rename(), .remove()) can delegate to either the raw AST or the language service as needed; src/codeBlockWriter provides an indentation-aware string builder used internally (and exposed) for generating source text.

Tech Stack - Pure TypeScript, organized as a monorepo (packages/ts-morph, packages/bootstrap, packages/common, packages/scripts) built with Deno tooling (deno.json/deno.lock) alongside npm packaging, bundled via Rollup (rollup.config.mjs), with a code-generation step (scripts/generation) that produces much of the wrapper-class boilerplate directly from the TypeScript compiler’s own type definitions to stay in sync across TS versions.

Code Quality - Tests run under Mocha (.mocharc.yml) with dedicated typeCheckDocumentation.ts and typeCheckLibrary.ts scripts that verify both the README’s code samples and the library’s own types actually compile, catching documentation drift that plain unit tests would miss; the breaking-changes.md file tracks API changes explicitly release over release, a sign of deliberate API stewardship for a library with a large public surface.

API Design - The chainable, getter-heavy API (sourceFile.getClasses()[0].getMethods()) mirrors how developers already think about ASTs, and the additional “structure” API (describing nodes as plain object literals) offers a declarative alternative to imperative builder calls for generation-heavy use cases, trading some API surface size for genuinely improved discoverability over the raw compiler API.