Migration Guide: v0.1.x → v0.2.0

Breaking Changes

This guide helps you migrate from migration-script-runner v0.1.x to @migration-script-runner/core v0.2.0.

Summary of Changes

Package Rename

The package has been renamed and moved to a scoped namespace under a GitHub organization:

What Before After
Package Name migration-script-runner @migration-script-runner/core
Repository vlavrynovych/msr migration-script-runner/msr-core
Documentation https://vlavrynovych.github.io/msr/ https://migration-script-runner.github.io/msr-core/

New Features

v0.2.0 includes new opt-in features that are fully backward compatible:

  • ✨ Display Limit Configuration - Limit console output for projects with many migrations
  • ✨ List Method - View migrations without running them
  • 📚 Comprehensive JSDoc - Complete documentation for all public APIs
  • 📖 GitHub Pages Documentation - Full documentation site with guides and examples

All changes are backward compatible. No code changes required to upgrade!

Breaking Changes

1. Package Name Change

Impact: HIGH - Affects all users

The npm package name has changed:

- migration-script-runner
+ @migration-script-runner/core

Action Required: Update package.json and all import statements.

2. Import Paths Change

Impact: HIGH - Affects all code files

All import statements must be updated:

- import { MigrationScriptExecutor } from 'migration-script-runner';
+ import { MigrationScriptExecutor } from '@migration-script-runner/core';

Migration Steps

Step 1: Update package.json

Replace the old package with the new scoped package:

npm uninstall migration-script-runner
npm install @migration-script-runner/core

Or update package.json directly:

{
  "dependencies": {
    "@migration-script-runner/core": "^0.2.0"
  }
}

Then run:

npm install

Step 2: Update Import Statements

Update all imports throughout your codebase:

TypeScript/JavaScript files:

// Before
import { MigrationScriptExecutor, Config } from 'migration-script-runner';

// After
import { MigrationScriptExecutor, Config } from '@migration-script-runner/core';

CommonJS:

// Before
const { MigrationScriptExecutor } = require('migration-script-runner');

// After
const { MigrationScriptExecutor } = require('@migration-script-runner/core');

Step 3: Update Migration Scripts

If your migration scripts import from the package:

// Before
import { IMigrationScript, IMigrationInfo } from 'migration-script-runner';

// After
import { IMigrationScript, IMigrationInfo } from '@migration-script-runner/core';

Step 4: Update Documentation References

If you reference MSR documentation in your code:

// Before
// See: https://vlavrynovych.github.io/msr/

// After
// See: https://migration-script-runner.github.io/msr-core/

Step 5: Test Everything

Run your tests to ensure everything works:

npm test

Run a test migration:

npm run migrate  # or however you run migrations

What Stays the Same

Good news: Only the package name changed. Everything else is identical!

✅ All APIs unchanged - No breaking changes to functionality ✅ Configuration works the same - Same Config and BackupConfig ✅ Migration scripts unchanged - Existing migrations work as-is ✅ Database handlers unchanged - IDatabaseMigrationHandler is the same ✅ Behavior unchanged - Same backup/restore, same execution flow

Quick Migration Tools

Find & Replace in VS Code/IDE

Find: from 'migration-script-runner' Replace: from '@migration-script-runner/core'

Find: require('migration-script-runner') Replace: require('@migration-script-runner/core')

Command Line (Unix/Linux/macOS)

Find all files that need updating:

grep -r "migration-script-runner" . --exclude-dir=node_modules

Replace in all TypeScript/JavaScript files:

find . -type f \( -name "*.ts" -o -name "*.js" \) -not -path "*/node_modules/*" \
  -exec sed -i '' 's/migration-script-runner/@migration-script-runner\/core/g' {} +

Command Line (Windows PowerShell)

Find all files:

Get-ChildItem -Recurse -Include *.ts,*.js -Exclude node_modules |
  Select-String "migration-script-runner"

Replace in all files:

Get-ChildItem -Recurse -Include *.ts,*.js -Exclude node_modules | ForEach-Object {
  (Get-Content $_) -replace 'migration-script-runner', '@migration-script-runner/core' | Set-Content $_
}

Complete Example

Before (v0.1.x) 

// package.json
{
  "dependencies": {
    "migration-script-runner": "^0.1.11"
  }
}

// src/migrate.ts
import { MigrationScriptExecutor, Config } from 'migration-script-runner';
import { FirebaseHandler } from './firebase-handler';

const config = new Config();
const handler = new FirebaseHandler(config);
const executor = new MigrationScriptExecutor(handler);

await executor.migrate();

After (v0.2.0) 

// package.json
{
  "dependencies": {
    "@migration-script-runner/core": "^0.2.0"
  }
}

// src/migrate.ts
import { MigrationScriptExecutor, Config } from '@migration-script-runner/core';
import { FirebaseHandler } from './firebase-handler';

const config = new Config();
const handler = new FirebaseHandler(config);
const executor = new MigrationScriptExecutor(handler);

await executor.migrate();

Only the package name and import changed!

Troubleshooting

Cannot find module ‘@migration-script-runner/core’

Cause: New package not installed

Solution:

npm install @migration-script-runner/core

Old package still in package-lock.json

Cause: Lock file not updated

Solution:

rm package-lock.json
rm -rf node_modules
npm install

TypeScript can’t find types

Cause: Cache issue

Solution:

rm -rf node_modules/.cache
npm install

CI/CD pipeline failing

Cause: CI config still references old package

Solution: Update CI configuration or use package.json dependencies (recommended):

npm ci  # installs from package-lock.json

Rollback Plan

If you need to rollback to the old version:

npm uninstall @migration-script-runner/core
npm install migration-script-runner@^0.1.11

Then revert your import statements:

import { MigrationScriptExecutor } from 'migration-script-runner';

The old package is deprecated and won’t receive updates. We recommend completing the migration when possible.

Status of Old Package

The migration-script-runner package on npm:

⚠️ Deprecated - Marked as deprecated with migration message 🔒 No longer maintained - All development happens in @migration-script-runner/core 📦 Still available - Won’t be unpublished for stability ❌ No updates - No bug fixes or new features

FAQ

Q: Do I have to migrate immediately? A: No, but we strongly recommend it. The old package won’t receive updates or bug fixes.

Q: Will my existing migrations still work? A: Yes! Only the package name changed. All functionality is identical.

Q: Can I use both packages during transition? A: No, they conflict. Choose one or the other. We recommend migrating all at once.

Q: What if I encounter a bug after migrating? A: Report it on GitHub Issues.

Q: Is there an automated migration tool? A: Use the find & replace commands above. Most IDEs can do this in seconds.

Q: Will there be more breaking changes? A: We’ll minimize breaking changes and always provide migration guides when they occur.

Need Help?

Migration completed? Don’t forget to update your team’s documentation! 🎉