Migration & Upgrade Guide

# Check current version
node --version

# Recommended: Node.js 18 LTS or 20 LTS
# Download from: https://nodejs.org/

# Verify installation
node --version
npm --version

# Clean install dependencies
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

# Check current version
pnpm --version

# Upgrade PNPM
npm install -g pnpm@latest

# Verify
pnpm --version

# Update lockfile
pnpm install

# Update Next.js
pnpm add next@latest -w

# Update related packages
pnpm add react@latest react-dom@latest -w

# Test build
pnpm build

# Run development server
pnpm dev

# Read upgrade guide
open https://nextjs.org/docs/upgrading

git checkout develop
git pull origin develop
git checkout -b upgrade/nextjs-15

# Update Next.js
pnpm add next@15 -w

# Update React (if required)
pnpm add react@latest react-dom@latest -w

# Update TypeScript types
pnpm add -D @types/react@latest @types/react-dom@latest -w

// next.config.js
// Check for deprecated options

const nextConfig = {
  // Remove deprecated options
  // Add new required options
  
  // Example: New image config in Next.js 15
  images: {
    remotePatterns: [/* ... */],
    // New options
  },
};

// Update imports if changed
// Old: import { useRouter } from 'next/router'
// New: import { useRouter } from 'next/navigation'

// Update route handlers
// Check API route syntax
// Verify middleware patterns

# Run type checking
pnpm typecheck

# Run tests
pnpm test

# Build application
pnpm build

# Test production build locally
pnpm start

# Run E2E tests
pnpm test:e2e

git push origin upgrade/nextjs-15

# Create PR
gh pr create --base develop --title "Upgrade to Next.js 15"

# Deploy to staging for testing
# Monitor for issues

# Check current version
turbo --version

# Update Turbo
pnpm add turbo@latest -w -D

# Update turbo.json if needed
# Check: https://turbo.build/repo/docs/getting-started/upgrade

# Test build
pnpm build

# Clear cache if issues occur
rm -rf .turbo
pnpm build

cd apps/dashboard

# Update Prisma
pnpm add prisma@latest @prisma/client@latest

# Verify versions match
pnpm prisma --version

# Generate migration from schema changes
pnpm prisma migrate dev --name describe_your_changes

# Example: Adding new field
pnpm prisma migrate dev --name add_user_bio_field

# Set production database URL
DATABASE_URL="your-production-url" pnpm prisma migrate deploy

# Or use environment variable
pnpm prisma migrate deploy

# Regenerate Prisma Client
pnpm prisma generate

# Restart application
pnpm dev

# Reset to previous migration
pnpm prisma migrate resolve --rolled-back <migration-name>

# Reset database (development only!)
pnpm prisma migrate reset

# Reapply migrations
pnpm prisma migrate dev

# Update all Radix packages
pnpm up "@radix-ui/*@latest" -w

# Test components after upgrade
pnpm dev

# Check for deprecation warnings in console

# Update Tailwind
pnpm add tailwindcss@latest -w -D

# Update plugins
pnpm add @tailwindcss/typography@latest -w -D

# Rebuild CSS
pnpm dev

// app/page.tsx
export default function Page() {
  return <div>Hello</div>;
}

// app/page.tsx
// No changes required for basic pages
export default function Page() {
  return <div>Hello</div>;
}

// But check for:
// - New caching behavior
// - Updated fetch API
// - Server Actions changes

<Image
  src="/image.jpg"
  alt="Description"
  width={500}
  height={300}
  layout="responsive"
/>

<Image
  src="/image.jpg"
  alt="Description"
  width={500}
  height={300}
  sizes="100vw"
  style={{ width: '100%', height: 'auto' }}
/>

// pages/api/hello.ts
export default function handler(req, res) {
  res.status(200).json({ message: 'Hello' });
}

// app/api/hello/route.ts
export async function GET(request: Request) {
  return Response.json({ message: 'Hello' });
}

// Add Suspense boundaries for better loading states
import { Suspense } from 'react';

export default function Page() {
  return (
    <Suspense fallback={<Loading />}>
      <AsyncComponent />
    </Suspense>
  );
}

// app/components/ServerComponent.tsx
// No 'use client' directive = Server Component

export default async function ServerComponent() {
  const data = await fetchData();
  
  return <div>{data.content}</div>;
}

// app/components/ClientComponent.tsx
'use client';

import { useState } from 'react';

export default function ClientComponent() {
  const [count, setCount] = useState(0);
  
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

# List all environment variables
cat apps/site/.env.local

# Check for deprecated variables
grep -r "OLD_VAR_NAME" apps/

// Before
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// After
const apiUrl = process.env.NEXT_PUBLIC_BASE_URL;

# Update env.template
# Update README
# Update configuration docs

# Update Vercel environment variables
vercel env add NEXT_PUBLIC_BASE_URL production

# Remove old variables
vercel env rm NEXT_PUBLIC_API_URL production

.\scripts\automation\create-issue.ps1

.\scripts\issue-management\create-issue-enhanced.ps1

# scripts/utilities/migrate-script-paths.ps1

$oldPaths = @{
    "automation\create-issue.ps1" = "issue-management\create-issue-enhanced.ps1"
    "automation\manage-pr.ps1" = "pr-management\automate-pr-unified.ps1"
}

foreach ($old in $oldPaths.Keys) {
    $new = $oldPaths[$old]
    Write-Host "Migrating: $old → $new"
    
    # Update references in other scripts
    Get-ChildItem -Path "scripts" -Recurse -Filter "*.ps1" | ForEach-Object {
        $content = Get-Content $_.FullName -Raw
        if ($content -match $old) {
            $content = $content -replace [regex]::Escape($old), $new
            Set-Content $_.FullName -Value $content
            Write-Host "  Updated: $($_.Name)"
        }
    }
}

$env:GITHUB_TOKEN = "ghp_token"
gh api ...

# Use gh auth login
gh auth login --scopes repo,project,workflow

# Refresh token
gh auth refresh --scopes repo,project,workflow

# Use in scripts
gh api ... # Automatically uses authenticated session

{
  // Before
  "pipeline": {
    "build": {
      "outputs": [".next/**"]
    }
  },
  
  // After
  "tasks": {
    "build": {
      "outputs": [".next/**"]
    }
  }
}

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "jest"
  }
}

{
  "scripts": {
    "dev": "turbo run dev --parallel",
    "build": "turbo run build",
    "test": "turbo run test --continue"
  }
}

// scripts/migrations/migrate-user-data.ts

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function migrateUserData() {
  // Get all users
  const users = await prisma.user.findMany();
  
  // Transform data
  for (const user of users) {
    await prisma.user.update({
      where: { id: user.id },
      data: {
        // Add new fields
        bio: user.profile?.bio || null,
        // Transform existing fields
        name: user.name?.trim(),
      },
    });
  }
  
  console.log(`Migrated ${users.length} users`);
}

migrateUserData()
  .catch(console.error)
  .finally(() => prisma.$disconnect());

DATABASE_URL="..." ts-node scripts/migrations/migrate-user-data.ts

pnpm test
# Verify all tests pass

pnpm typecheck
# Fix any type errors

pnpm build
# Ensure builds successfully

pnpm test:e2e
# Test critical user flows

# Run Lighthouse
pnpm build
pnpm start
# Open localhost:3000
# Run Lighthouse audit

# Revert to previous commit
git revert HEAD

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

# Force push (if necessary)
git push origin develop --force

# On Vercel
vercel rollback

# Or redeploy previous commit
vercel --prod

# Rollback migration
pnpm prisma migrate resolve --rolled-back <migration-name>

# Or restore from backup
# (See your database provider's documentation)

// Enable/disable features without deploying
const features = {
  newFeature: process.env.FEATURE_NEW_FEATURE === 'true',
};

export default function Component() {
  if (!features.newFeature) {
    return <OldComponent />;
  }
  return <NewComponent />;
}

# Deploy to subset of users
vercel --prod --alias canary.example.com

# If successful, promote to main
vercel alias canary.example.com www.example.com

# Backup old config
Copy-Item scripts/configuration/agent-config.json `
          scripts/configuration/agent-config-v1-backup.json

# Run migration script
.\scripts/utilities/migrate-agent-config-v1-to-v2.ps1

# Verify new configuration
Get-Content scripts/configuration/agent-assignment-config.json

# Test new system
.\scripts\agent-management\manage-multi-agent-system.ps1 -Operation status