Upgrade Guide

This guide covers upgrading between Stacks.js versions, including breaking changes and migration steps.

General Upgrade Process

Step 1: Check Current Version

buddy --version
# or
bun pm ls @stacksjs/stacks

Step 2: Review Release Notes

Before upgrading, review the changelog for:

Breaking changes
Deprecation notices
New features
Bug fixes

Step 3: Update Dependencies

Use the framework-aware upgrade path so generated files, migrations, and the declared toolchain are considered together:

buddy upgrade --help
buddy upgrade

Step 4: Run Upgrade Command

# Run automated migrations and updates
buddy upgrade

# Check for issues
buddy doctor

Step 5: Test Your Application

# Run tests
buddy test

# Type check
buddy test:types

# Build
buddy build

Version-Specific Upgrades

Upgrading to 1.0 (from 0.x)

When Stacks 1.0 is released, this section will contain specific migration instructions.

Anticipated changes:

API stabilization
Potential breaking changes from alpha/beta feedback
New features and improvements

Pre-1.0 Upgrades

During the pre-1.0 line, breaking changes may occur more frequently. Always:

Pin your version in package.json
Test thoroughly before deploying
Review all changelog entries between versions

Common Breaking Changes

Configuration Changes

When configuration structure changes:

// Old structure (example)
export default {
  database: 'mysql',
  host: 'localhost',
}

// New structure (example)
export default {
  driver: 'mysql',
  connection: {
    host: 'localhost',
  },
}

Migration:

# The upgrade command typically handles this
buddy upgrade

# Or manually update config files

API Changes

When method signatures change:

// Old API
User.find(1, ['name', 'email'])

// New API
User.select('name', 'email').find(1)

Migration:

Search codebase for old patterns
Update to new syntax
Run tests to verify

Import Path Changes

When package structure changes:

// Old import
import { Router } from '@stacksjs/framework'

// New import
import { Router } from '@stacksjs/router'

Migration:

# Find and replace across project
grep -r "@stacksjs/framework" --include="*.ts" app/

Database Migrations

When schema changes are required:

# Check migration status
buddy migrate:status

# Run pending migrations
buddy migrate

# If issues occur, check migration files
ls database/migrations/

Automated Codemods

Stacks provides codemods for common migrations:

# List available codemods
buddy codemod --list

# Run specific codemod
buddy codemod update-imports-v1

# Dry run (show changes without applying)
buddy codemod update-imports-v1 --dry-run

Handling Deprecations

Deprecation Warnings

When running your app, you may see deprecation warnings:

[DEPRECATED] User.find() with array parameter is deprecated.
Use User.select().find() instead. Will be removed in v1.0.

Actions:

Note the version where removal occurs
Update code before that version
Test the new implementation

Finding Deprecated Usage

# Search for deprecated patterns
buddy deprecations:check

# Output example:
# ┌─────────────────────────────────────────────────────────┐
# │ Deprecated Usage Found                                   │
# ├─────────────────────────────────────────────────────────┤
# │ File: app/Controllers/UserController.ts:25              │
# │ Pattern: User.find(id, fields)                          │
# │ Replace with: User.select(...fields).find(id)           │
# │ Removal: v1.0                                           │
# └─────────────────────────────────────────────────────────┘

Rollback Procedures

If Upgrade Fails

# Restore previous dependencies
git checkout bun.lockb
bun install

# Or restore specific package version
bun add @stacksjs/stacks@0.x.x

Database Rollback

# Rollback last migration batch
buddy migrate:rollback

# Rollback specific number of batches
buddy migrate:rollback --step=3

# Rollback all migrations
buddy migrate:reset

Git-based Rollback

# View recent commits
git log --oneline -10

# Revert to previous state
git revert HEAD

# Or hard reset (destructive)
git reset --hard HEAD~1

Dependency Compatibility

Bun Version

# Check Bun version
bun --version

# Install the version declared by the project toolchain
pantry install

# The audited source declares Bun ^1.3.0
buddy doctor

TypeScript Version

# Run the project-owned typecheck path
buddy test:types

Do not add or upgrade TypeScript independently when the project receives it through the shared better-dx toolchain.

Node.js Compatibility

While Stacks runs on Bun, some tools may require Node.js:

# For tools requiring Node.js
node --version  # Should be 18+ for compatibility

Best Practices

Before Upgrading

Backup your database
```
buddy db:backup
```

Commit current state

git add -A
git commit -m "chore: pre-upgrade checkpoint"

Create upgrade branch
```
git checkout -b upgrade/stacks-x.x
```
Review breaking changes
- Read full changelog
- Check GitHub issues for known problems

During Upgrade

Upgrade incrementally
- Don't skip major versions
- Test after each upgrade
Fix issues as they appear
- Address deprecation warnings
- Update deprecated APIs
Run full test suite
```
buddy test
buddy typecheck
buddy lint
```

After Upgrading

Verify in staging
- Deploy to staging environment
- Run smoke tests
Monitor production
- Watch error rates
- Check performance metrics
Document changes
- Note any custom migrations
- Update team documentation

Troubleshooting Upgrades

Type Errors After Upgrade

# Regenerate types
buddy types:generate

# Clear TypeScript cache
rm -rf node_modules/.cache

# Restart TypeScript server in IDE

Module Resolution Issues

# Clean install
rm -rf node_modules bun.lockb
bun install

# Verify lockfile
bun install --frozen-lockfile

Configuration Validation Errors

# Validate configuration
buddy config:validate

# Show current configuration
buddy config:show

Database Compatibility

# Check database version
buddy db:version

# Verify connection
buddy db:ping

# Run fresh migrations (development only)
buddy migrate:fresh

Getting Help

If you encounter issues during upgrade:

Search existing issues: GitHub Issues
Check Discord: Real-time community help
Create detailed issue: Include versions, error messages, and steps to reproduce