Vercel Upgrade Migration

Overview

Safely upgrade Vercel CLI, Node.js runtime versions, and framework versions (especially Next.js) on Vercel. Covers breaking change detection, vercel.json schema changes, and rollback strategy.

Current State

!

vercel --version 2>/dev/null || echo 'Vercel CLI not installed'

node --version 2>/dev/null || echo 'N/A'

cat package.json 2>/dev/null | jq -r '.dependencies.next // "no next.js"' 2>/dev/null || echo 'N/A'

Prerequisites

• Current Vercel CLI installed
• Git for version control
• Test suite available
• Preview deployment for testing

Instructions

Step 1: Check Current Versions

# Current CLI version
vercel --version

# Current Node.js runtime on Vercel
cat package.json | jq '.engines.node'
# Or check vercel.json
cat vercel.json | jq '.functions'

# Check for available CLI updates
npm outdated -g vercel

# Check framework version
npm ls next react

Step 2: Upgrade Vercel CLI

# Upgrade to latest
npm install -g vercel@latest

# Or specific version
npm install -g vercel@39

# Verify
vercel --version

CLI breaking changes to watch for:

• v28+:

  vercel env pull

  output format changed
• v32+:

  vercel dev

  uses new function runtime
• v37+:

  vercel.json

  builds

  property deprecated in favor of framework detection

Step 3: Upgrade Node.js Runtime

// package.json — specify the Node.js version
{
  "engines": {
    "node": "20.x"
  }
}

Available runtimes on Vercel:

# Test locally with the target Node version first
nvm use 20
npm test
npm run build

Step 4: Upgrade Next.js on Vercel

# Use the Next.js upgrade codemod
npx @next/codemod@latest upgrade

# Or manual upgrade
npm install next@latest react@latest react-dom@latest

# Check for breaking changes
npx @next/codemod --dry-run

Key Next.js migration points:

• 13 → 14: App Router stable, Turbopack available, Server Actions stable
• 14 → 15:

  fetch

  no longer cached by default,

  cookies()

  is async,

  NextRequest.geo

  removed (use

  geolocation()

  from

  @vercel/functions

  )
• vercel.json changes:

  rewrites

  /

  redirects

  in

  next.config.js

  take precedence over

  vercel.json

Step 5: Test in Preview Before Production

# Create a branch for the upgrade
git checkout -b upgrade/vercel-cli-39

# Make changes and push
git add -A && git commit -m "chore: upgrade vercel CLI and Node.js 20"
git push -u origin upgrade/vercel-cli-39

# Vercel auto-deploys a preview — test it
vercel ls | head -3
curl -s https://my-app-git-upgrade-vercel-cli-39-team.vercel.app/api/health

# Run full test suite against preview
npm test -- --env=preview

Step 6: Rollback Strategy

# If the upgrade breaks production — instant rollback
vercel rollback

# Pin to a specific CLI version in CI
# .github/workflows/deploy.yml
# - run: npm install -g vercel@38  # pin to known good version

# Revert Node.js runtime
# Change engines.node back in package.json
# Push and redeploy

vercel.json Schema Migration

Deprecated

builds

// Old (deprecated):
{
  "builds": [
    { "src": "api/**/*.ts", "use": "@vercel/node" }
  ]
}

// New (framework auto-detection):
{
  "functions": {
    "api/**/*.ts": {
      "runtime": "nodejs20.x",
      "maxDuration": 30
    }
  }
}

Output

• Vercel CLI upgraded to latest version
• Node.js runtime version updated in package.json
• Framework upgraded with codemods applied
• Preview deployment tested before production promotion
• Rollback strategy documented

Error Handling

Build failed

npm ls

Module not found

npx @next/codemod

vercel.json

builds

functions

FUNCTION_INVOCATION_FAILED

Resources

• Vercel CLI Changelog
• Node.js Runtime on Vercel
• Next.js Upgrade Guide
• vercel.json Reference

Next Steps

For CI/CD integration, see

vercel-ci-integration