ts-morph

library28.0.0jsnpmunverified

ts-morph (formerly ts-simple-ast) is a robust library that wraps the TypeScript Compiler API, offering a more user-friendly and programmatic way to navigate, analyze, and manipulate TypeScript and JavaScript code. It provides an in-memory file system where all changes are tracked until explicitly saved, allowing for complex refactoring and code generation tasks. The library maintains strong compatibility with recent TypeScript versions, often releasing new major versions shortly after a new TypeScript compiler release. The current stable version is 28.0.0, which supports TypeScript 6.0. Key differentiators include its extensive wrapper API, enabling easy traversal and modification of AST nodes, and its ability to fall back to the raw `compilerNode` when advanced compiler API access is needed, providing full flexibility for complex scenarios.

serialization devops

npm install ts-morph

github ↗package ↗

INSTALL

IMPORT

SIG · TS-MORPH

ts-morph

serializationjavascriptv28.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Project

✓ import { Project } from 'ts-morph';

✗ const Project = require('ts-morph').Project;

Primary entry point for creating and managing TypeScript projects.

StructureKind

✓ import { StructureKind } from 'ts-morph';

✗ import * as ts from 'ts-morph'; const StructureKind = ts.StructureKind;

Used for programmatically defining AST structures like classes, enums, and interfaces.

Node

✓ import { Node } from 'ts-morph';

✗ import { SyntaxKind } from 'typescript'; // Not the ts-morph Node class

The base class for all wrapped TypeScript AST nodes, providing common manipulation and traversal methods.

Demonstrates initializing a project, adding and creating source files, navigating the AST, manipulating a class, and saving changes.

import { Project, StructureKind } from "ts-morph"; async function main() { const project = new Project({ // Optionally specify compiler options, tsconfig.json, or an in-memory file system. // If initialized with a tsconfig.json, it automatically loads associated source files. }); // Add source files or create new ones project.addSourceFilesAtPaths("src/**/*.ts"); const myClassFile = project.createSourceFile("src/MyClass.ts", "export class MyClass {}"); const myEnumFile = project.createSourceFile("src/MyEnum.ts", { statements: [{ kind: StructureKind.Enum, name: "MyEnum", isExported: true, members: [{ name: "member" }], }], }); // Get and manipulate nodes const myClass = myClassFile.getClassOrThrow("MyClass"); console.log(myClass.getName()); // "MyClass" myClass.rename("NewName"); myClass.addProperty({ name: "myProp", initializer: "5", has;// Indicates if property should have a question mark (optional) or not }); // Asynchronously save all changes to the file system await project.save(); console.log('Project changes saved.'); } main().catch(console.error);

Debug

Known issues

breakingMajor versions of ts-morph are typically released to support new TypeScript compiler versions. Upgrading ts-morph often requires upgrading your project's TypeScript version to match its peer dependency, and vice-versa.

fix

Always check ts-morph's release notes (e.g., CHANGELOG.md) for its supported TypeScript version before upgrading. Ensure your `typescript` dependency in `package.json` aligns with ts-morph's requirements.

affects: >=22.0.0

breakingVersion 28.0.0 introduces support for TypeScript 6.0, which may include breaking changes aligning with the underlying TypeScript API changes.

fix

Review the TypeScript 6.0 release notes (e.g., 'https://devblogs.microsoft.com/typescript/announcing-typescript-6-0/') and ts-morph's breaking changes documentation for specific adjustments needed in your codebase.

affects: >=28.0.0

breakingThe method `Node.prototype.forgetDescendants()` in ts-morph v22.0.0 and later no longer returns the node itself. It now returns `void`.

fix

If you chained calls after `forgetDescendants()`, you will need to re-structure your code to explicitly get the node before making subsequent calls, as it no longer returns `this`.

affects: >=22.0.0

gotchaBrowser support for ts-morph was temporarily broken in version 26.0.0 due to missing browser fields in its `package.json`, causing issues with modules like `fs/promises` in browser environments.

fix

Upgrade to ts-morph `27.0.2` or higher to resolve browser compatibility issues.

affects: 26.0.0 - 27.0.0

Errors

Common errors & fixes

Cannot find module 'ts-morph'

The package is not installed, or there's a mismatch between CommonJS `require` and ES module `import` syntax, or an incorrect import path.

fix

Ensure `ts-morph` is installed (`npm install ts-morph`). If using CommonJS, use `const { Project } = require('ts-morph');`. If using ES modules (recommended), ensure `"type": "module"` is set in `package.json` or use `.mjs` files.

Error: You are using TypeScript X.Y.Z, but ts-morph was built with TypeScript A.B.C.

The installed version of `ts-morph` has a peer dependency on a specific TypeScript version, and your project's TypeScript version does not match.

fix

Adjust your project's `typescript` dependency in `package.json` to match the version required by `ts-morph` (check ts-morph's `package.json` or documentation). Then run `npm install`.

InvalidOperationError: The operation is invalid for a node that has been forgotten.

Attempting to interact with an AST node that has been 'forgotten' (removed from the project's internal AST representation), typically after a manipulation that invalidates the node's position or existence.

fix

After significant AST manipulations (e.g., deleting a node, moving files), re-obtain the relevant nodes from the project or their parents. If a node is no longer needed, ensure you don't try to access its properties or methods.

Upgrade

Version history

28.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dsherret/ts-morph ↗

packagehttps://www.npmjs.com/package/ts-morph ↗