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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Migration
✓ import { Migration } from 'typescript-migration';
✗ const { Migration } = require('typescript-migration');
The primary class to extend when creating a new type migration. CommonJS `require` is not officially supported and may lead to issues.
Migrator
✓ import { Migrator } from 'typescript-migration';
✗ const { Migrator } = require('typescript-migration');
The core class responsible for running defined migrations. Typically used internally by the CLI, but can be instantiated for programmatic execution.
SourceFile
✓ import { SourceFile } from 'ts-morph';
While not directly exported by `typescript-migration`, `SourceFile` from `ts-morph` is a critical type for interacting with the AST within your `Migration` classes. You will import this directly from `ts-morph`.
Demonstrates defining an `up` and `down` TypeScript type migration and applying it programmatically to a source file. Typically, this would be run via the CLI against a directory of migration files.
import { Migration } from 'typescript-migration';
import { SourceFile } from 'ts-morph';
import * as path from 'path';
import * as fs from 'fs';
// 1. Define your migration in a file, e.g., 'src/migrations/001-rename-user-interface.ts'
// This migration renames an interface from 'IUser' to 'User'.
class RenameUserInterface extends Migration {
name = 'Rename IUser to User Interface';
async up(sourceFile: SourceFile): Promise<void> {
const oldInterface = sourceFile.getInterface('IUser');
if (oldInterface) {
oldInterface.rename('User');
this.log(`Renamed IUser to User in ${sourceFile.getFilePath()}`);
}
}
async down(sourceFile: SourceFile): Promise<void> {
const newInterface = sourceFile.getInterface('User');
if (newInterface) {
newInterface.rename('IUser');
this.log(`Renamed User back to IUser in ${sourceFile.getFilePath()}`);
}
}
}
// For demonstration, create a dummy TypeScript file to migrate.
const dummyFilePath = path.join(process.cwd(), 'temp-source.ts');
const dummyContent = `interface IUser { id: string; name: string; }\nconst user: IUser = { id: '1', name: 'Alice' };`;
// For CLI usage, you would place this migration file in a designated migrations directory.
// For programmatic usage (shown here for simplicity):
async function runMigrationProgrammatically() {
// Ensure temp-source.ts exists for the demo
fs.writeFileSync(dummyFilePath, dummyContent);
console.log('Created temp-source.ts');
// To run this via the CLI, you would save RenameUserInterface to a file
// and execute: npx typescript-migration run --up path/to/migrations_folder
// Programmatic execution example:
const { Migrator } = await import('typescript-migration');
const migrator = new Migrator();
// Instantiate your migration
const migrationInstance = new RenameUserInterface();
// Apply the 'up' migration to the dummy file
console.log('\n--- Running UP migration ---');
await migrator.run([migrationInstance], [dummyFilePath], 'up');
console.log('Migration UP finished.');
// Verify changes (read the file content after migration)
const updatedContent = fs.readFileSync(dummyFilePath, 'utf8');
console.log('\nUpdated temp-source.ts content:\n', updatedContent);
// Revert the 'down' migration
console.log('\n--- Running DOWN migration ---');
await migrator.run([migrationInstance], [dummyFilePath], 'down');
console.log('Migration DOWN finished.');
const revertedContent = fs.readFileSync(dummyFilePath, 'utf8');
console.log('\nReverted temp-source.ts content:\n', revertedContent);
// Clean up
fs.unlinkSync(dummyFilePath);
console.log('\nCleaned up temp-source.ts');
}
runMigrationProgrammatically().catch(console.error);
ts-migration --version
Errors
Common errors & fixes
Error: Cannot find module 'typescript-migration' or its corresponding type declarations.
The package is not installed or the TypeScript configuration does not correctly resolve modules.
fixEnsure the package is installed: `npm install typescript-migration` or `yarn add typescript-migration`. For programmatic usage, ensure your `tsconfig.json` has `moduleResolution` set appropriately (e.g., `node`).
TypeError: project.getSourceFile is not a function (or similar ts-morph error)
Incorrect usage of `ts-morph` API within a migration, or `ts-morph` itself might be an incompatible version.
fixConsult the `ts-morph` documentation for the correct API usage. Ensure `ts-morph` is installed as a dependency and its version is compatible with `typescript-migration` (though this package is a CLI, your migration files are TypeScript). The `Migration` class provides the `sourceFile` argument directly.
Audit
Dependencies
commanderrequiredUsed for building the command-line interface (CLI).
globrequiredUsed for matching file paths to locate migration files and source code.
ts-morphrequiredCore dependency for programmatic manipulation of TypeScript Abstract Syntax Trees (ASTs), which is fundamental to how migrations are applied.