TypeScript AST Wrapper and Code Manipulator

Common errors

• Cannot find module 'ts-morph'

  cause 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.

  cause 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.

  cause 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.

Warnings

• breaking Major 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.
• breaking Version 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.
• breaking The 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`.
• gotcha Browser 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.

Install

• npm install ts-morph npm
• yarn add ts-morph yarn
• pnpm add ts-morph pnpm

Imports

• Project
  wrong:

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

  correct:

  import { Project } from 'ts-morph';

  Primary entry point for creating and managing TypeScript projects.
• StructureKind
  wrong:

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

  correct:

  import { StructureKind } from 'ts-morph';

  Used for programmatically defining AST structures like classes, enums, and interfaces.
• Node
  wrong:

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

  correct:

  import { Node } from 'ts-morph';

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

Quickstart

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);