Migrations

Why Migrations Exist

As Supaslidev evolves, new features sometimes require changes to:

• Dependency versions in presentation package.json files
• Workspace configuration files
• Catalog entries in pnpm-workspace.yaml
• State tracking in .supaslidev/

Rather than requiring manual updates (which are error-prone and tedious), migrations automate these changes. When you update the CLI, any necessary workspace transformations are packaged as migrations that you can preview and apply.

How Migrations Work

The migration system follows these principles:

Versioned and ordered: Each migration has a unique ID and runs in a specific sequence. The system tracks which migrations have been applied to avoid running them twice.

Reversible with backups: Before applying migrations, the system creates a backup of your workspace. If something goes wrong, it automatically restores from the backup.

Preview before apply: You always see what changes will happen before they're made. No surprises.

Journaled: Every migration attempt is logged with timestamps and outcomes, creating an audit trail in .supaslidev/migration-journal.json.

Checking Migration Status

Use the status command to see if any migrations are pending:

supaslidev status

The output includes a Pending Migrations count. A value of 0 means your workspace is up to date.

Supaslidev Status
────────────────────────────────────────

CLI Version:      0.1.0
State Version:    0.1.0

Created:          Jan 15, 2025, 10:30 AM
Last Updated:     Jan 20, 2025, 02:15 PM

Pending Migrations: 0

...

When migrations are available, the count shows how many need to be applied:

Pending Migrations: 1

Previewing Migrations

Before applying migrations, preview what changes will occur:

supaslidev migrate

Without the --apply flag, this runs in dry-run mode. You see exactly which migrations would run and what they do:

Supaslidev Migrate
────────────────────────────────────────

Mode: Dry Run (no changes will be made)

Migration Preview (Dry Run)
==================================================

Migrations to apply: 1

  → slidev-51-to-52
    Migrate Slidev 51.x to 52.x by updating @slidev/cli
    and vue dependencies to use catalog versions

Run with --apply to execute migrations.

The preview shows:

• Migration ID: A unique identifier for the migration
• Description: What the migration does
• Breaking flag: Some migrations are marked as breaking changes

Running Migrations

Once you've reviewed the preview, apply migrations with:

supaslidev migrate --apply

The migration runner:

1. Creates a backup of your workspace in .supaslidev/backups/
2. Executes each pending migration in order
3. Records success in the migration journal
4. Deletes the backup on success

Supaslidev Migrate
────────────────────────────────────────

Migration Complete
==================================================

Applied 1 migration(s):
  ✓ slidev-51-to-52

✓ All migrations applied successfully

What Happens During Migration

A typical migration performs these steps:

1. Backup Creation

Before any changes, the system copies your workspace files (excluding node_modules, .git, dist, and other generated directories) to .supaslidev/backups/. Each backup has a timestamped ID.

2. Migration Execution

The migration code runs, making the necessary changes. For example, a dependency migration might:

• Scan presentation package.json files
• Update version specifiers to use catalog:
• Modify pnpm-workspace.yaml catalog entries

3. State Update

After successful execution, the migration ID is recorded in .supaslidev/state.json to prevent re-running.

4. Journal Entry

A record is added to .supaslidev/migration-journal.json with the timestamp, outcome, and any error details.

5. Cleanup

On success, the backup is deleted to save disk space. On failure, the backup is preserved and automatically restored.

Handling Failures

If a migration fails:

1. The error is logged to the journal
2. Your workspace is automatically restored from the backup
3. The backup is preserved for debugging
4. The CLI exits with a non-zero status

Supaslidev Migrate
────────────────────────────────────────

Migration Failed
==================================================

Failed migration: slidev-51-to-52
Error: Unable to parse package.json in presentations/broken-talk

Workspace has been restored from backup.
Backup preserved: backup-2025-01-20T14-30-00-000

✗ Migration failed

Your workspace returns to its pre-migration state. You can fix the issue and try again.

Migration Journal

The journal at .supaslidev/migration-journal.json tracks all migration activity:

{
  "entries": [
    {
      "migrationId": "slidev-51-to-52",
      "appliedAt": "2025-01-20T14:30:00.000Z",
      "backupId": "backup-2025-01-20T14-30-00-000",
      "success": true,
      "rolledBack": false
    }
  ]
}

Each entry records:

• migrationId: Which migration ran
• appliedAt: When it ran
• backupId: The associated backup
• success: Whether it completed successfully
• rolledBack: Whether it was rolled back due to failure
• error: Error message if applicable

Interactive Migrations

Some migrations require user input. For example, when migrating Slidev versions, you might need to choose which presentations should use the new catalog dependency versus keeping their pinned versions.

The CLI prompts you for these decisions during migrate --apply:

The following presentations have pinned Slidev versions:

  quarterly-review: @slidev/cli@51.2.0
  product-launch: @slidev/cli@51.5.0

Select presentations to migrate to catalog version (^52.0.0):
  [x] quarterly-review
  [x] product-launch
  [ ] Keep all presentations on current versions

Workspace State

The .supaslidev/state.json file tracks your workspace metadata including applied migrations:

{
  "cliVersion": "0.1.0",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "lastUpdatedAt": "2025-01-20T14:30:00.000Z",
  "migrations": ["slidev-51-to-52"]
}

The migrations array lists all migrations that have been applied. The migration runner checks this to determine which migrations are pending.

Best Practices

Always preview first: Run supaslidev migrate without --apply to understand what will change.

Commit before migrating: Ensure your workspace has no uncommitted changes so you can easily see what the migration modified.

Review the changes: After migrating, check the git diff to verify the changes make sense.

Run pnpm install: Some migrations modify package.json files or the catalog. Run pnpm install afterward to update the lockfile.

Next Steps

Learn about the monorepo architecture that migrations help maintain, or explore the dashboard CLI for managing presentations.