migration-kit

library0.0.1jsnpmunverified

migration-kit is a library for building project-specific migration runners. It helps migration packages check runtime and dependency requirements, scan config files, run code transforms, and stop when a change still needs human review. Current stable version is 0.0.1. Release cadence is unknown. Key differentiators: provides a structured, ordered flow combining environment checks, dependency updates, config changes, and API code transforms using jscodeshift and ast-grep behind a shared transformer contract. It is opinionated about ordering (environment checks first, then dependencies, then package version updates, then config changes, then API changes) and requires explicit human review blocking for safety. Compared to using jscodeshift or ast-grep alone, migration-kit adds a complete runner framework with progress reporting and consistency across multi-step migrations.

devops testing

npm install migration-kit

package ↗

INSTALL

IMPORT

SIG · MIGRATION-KIT

migration-kit

devopsjavascriptv0.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

createMigrationRunner

✓ import { createMigrationRunner } from 'migration-kit'

✗ const { createMigrationRunner } = require('migration-kit')

migration-kit is ESM-only; CommonJS require is not supported.

runtime

✓ import { runtime } from 'migration-kit'

✗ import runtime from 'migration-kit'

runtime is a named export, not a default export.

transformer

✓ import { transformer } from 'migration-kit'

✗ import { astGrep } from 'migration-kit'

transformer is an object containing astGrep, jscodeshift, etc. Do not destructure directly from the package.

Creates a full migration runner with environment checks, dependency updates, config scanning, and API code transforms.

import { createMigrationRunner, runtime, transformer } from 'migration-kit'; import { readFileSync } from 'node:fs'; const runner = createMigrationRunner({ name: 'Migration to 2.x', from: '1.x', to: '2.x', configPath: ['migration.config.ts'], environment: [runtime.node({ version: '>=20.0.0' })], peerDependencies: [{ dependency: 'target-package', requiredVersion: '>=2.0.0' }], packageVersionUpdates: [{ dependency: 'target-package', to: '^2.0.0' }], configChanges: [{ title: 'Legacy mode removed', description: 'Remove legacyMode from config.', level: 'warning', shouldBlock: (filePath) => { const source = readFileSync(filePath, 'utf8'); return source.includes('legacyMode') ? { reason: 'Remove legacyMode' } : false; } }], apiChanges: [{ title: 'Replace legacy API', level: 'warning', files: ['src/**/*.ts'], transform: transformer.astGrep('legacyApi()', { replace: 'nextApi()' }) }] }); await runner.run();

Debug

Known issues

gotchamigration-kit is designed for building project-specific runners, not for running directly on user codebases.

fix

Use migration-kit as a dependency in your own migration package, not as a direct CLI tool.

affects: >=0.0.0

deprecatedpeerDependencies configuration key may change in future versions; check updates.

fix

Monitor the package's release notes for any changes to the options schema.

affects: 0.0.1

gotchaThe package is in early alpha (0.0.1); API stability is not guaranteed.

fix

Lock the version and test thoroughly before using in production.

affects: 0.0.1

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND: Cannot find package 'ast-grep' imported from 'migration-kit'

Missing optional peer dependency ast-grep when using transformer.astGrep()

fix

Install ast-grep via pnpm add ast-grep

TypeError: createMigrationRunner is not a function

CommonJS require() used instead of ESM import

fix

Use import { createMigrationRunner } from 'migration-kit' and ensure package.json has "type": "module"

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

ast-grepoptionalPeer dependency required for astGrep transformer helper

jscodeshiftoptionalPeer dependency required for jscodeshift transformer helper

Agent activity

5 hits · last 30 days

node

Amazon

Resources

packagemigration-kit ↗