SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsnextjs-upgrade-assistant

nextjs-upgrade-assistant

Coding & development

View repository

Updated 10-15 21:47

About this skill

Next.js Upgrade Assistant

Version: 1.0 (Next.js 15 → 16) Author: FrankX AI Systems Last Updated: 2025-10-24

Overview

Automated assistant for upgrading Next.js projects to version 16, with comprehensive migration support and MCP-powered guidance.

Pre-Upgrade Checklist

Before starting the upgrade, verify:

  • Project uses Git (for easy rollback)
  • All changes are committed
  • Tests are passing
  • Dependencies are up to date (except Next.js)
  • Node.js version is 18.18.0 or higher
  • Backup of production database (if applicable)

Reference

The full detail lives in references/ and loads only when needed:

Automated Migration with Codemods

Next.js provides codemods for automated migration:

# Run Next.js codemods via next-devtools-mcp
npx @next/codemod upgrade

# Specific transformations
npx @next/codemod built-in-next-font .
npx @next/codemod new-link .
npx @next/codemod next-image-to-legacy-image .

Query next-devtools-mcp for migration help:

  • Ask about specific migration patterns
  • Request codemod recommendations
  • Get examples for new features

Breaking Changes in Next.js 16

1. Removed Features

  • getStaticProps (use Server Components)
  • getServerSideProps (use Server Components)
  • getInitialProps (use Server Components)
  • pages/ directory in new apps (use app/)

2. Changed Defaults

  • Server Components are default (was opt-in)
  • fetch() caching defaults changed
  • Dynamic routes require explicit generateStaticParams

3. API Changes

  • Middleware runtime configuration
  • Image component props
  • Font optimization syntax

Common Issues & Solutions

Issue 1: Build Errors After Upgrade

Problem: Module not found or Type errors

Solution:

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Rebuild
npm run build

Issue 2: Hydration Errors

Problem: Hydration mismatch warnings

Solution:

// Ensure consistent rendering
// Bad
<time>{new Date().toString()}</time>

// Good
'use client'
import { useEffect, useState } from 'react'

function ClientTime() {
  const [time, setTime] = useState('')

  useEffect(() => {
    setTime(new Date().toString())
  }, [])

  return <time suppressHydrationWarning>{time}</time>
}

Issue 3: Server Actions Not Working

Problem: Server Actions return undefined or errors

Solution:

// Ensure 'use server' is at the top
'use server'

// Return serializable data only
export async function myAction() {
  // Bad - can't serialize Date objects
  return { date: new Date() }

  // Good - serialize first
  return { date: new Date().toISOString() }
}

Issue 4: Cache Not Invalidating

Problem: Data not updating after mutations

Solution:

'use server'

import { revalidatePath, revalidateTag } from 'next/cache'

export async function updatePost(id: string, data: any) {
  await db.post.update({ where: { id }, data })

  // Revalidate specific paths
  revalidatePath(`/posts/${id}`)
  revalidatePath('/posts')

  // Or use tags
  revalidateTag('posts')
}

MCP Integration for Upgrades

Use next-devtools-mcp for:

  • Migration guidance and codemods
  • Best practices for new features
  • Documentation lookup
  • Example code for Next.js 16 patterns

Use built-in MCP (after upgrade) for:

  • Monitoring application state
  • Debugging runtime issues
  • Inspecting Server Actions
  • Analyzing performance

Post-Upgrade Optimization

After successful upgrade:

  1. Enable New Features

    • Try Partial Prerendering
    • Use enhanced caching
    • Implement new metadata options

  2. Refactor Old Patterns

    • Convert Client Components to Server Components where possible
    • Replace fetch with native caching
    • Use Server Actions instead of API routes

  3. Optimize Performance

    • Review bundle size
    • Optimize images
    • Implement lazy loading
    • Check Core Web Vitals

  4. Update Documentation

    • Document new patterns used
    • Update setup guides
    • Note any breaking changes for team

Rollback Plan

If upgrade fails:

# Revert via Git
git reset --hard HEAD~1

# Or checkout previous commit
git checkout <previous-commit-hash>

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Test
npm run dev

Upgrade Checklist

  • Review breaking changes
  • Update dependencies
  • Update configuration files
  • Run codemods
  • Fix TypeScript errors
  • Fix linting issues
  • Update tests
  • Test locally
  • Deploy to staging
  • Run smoke tests
  • Deploy to production
  • Monitor logs
  • Update documentation

Success Criteria

Upgrade is successful when:

  • ✅ Build completes without errors
  • ✅ All tests pass
  • ✅ Type checking passes
  • ✅ Dev server runs smoothly
  • ✅ Production build works
  • ✅ Core Web Vitals maintained or improved
  • ✅ All features work as expected
  • ✅ No console errors or warnings
  • ✅ Built-in MCP connects (when dev server running)

Resources

This assistant provides a comprehensive upgrade path from Next.js 15 to 16 with minimal downtime and maximum reliability.