Upgrading to Next.js 15 Guide

Next.js 15 introduces significant enhancements, including support for React 19, improved caching mechanisms, and a stable release of Turbopack for development. This tutorial will guide you through the process of upgrading your existing Next.js application to version 15, ensuring a smooth transition and optimal utilization of the new features.

Prerequisites

Before upgrading, ensure you have the following:

• A Next.js 14 application
• Node.js 18 or later
• A recent version of npm or yarn
• A backup of your current project (recommended)

Step 1: Update Dependencies

Before proceeding with the upgrade, it's essential to update your project's dependencies to avoid compatibility issues.

Check Current Version

Run the following command to verify your current Next.js version:

npx next --version

If you are running an older version, proceed with updating the dependencies:

npm install next@latest react@latest react-dom@latest eslint-config-next@latest

For Yarn users:

yarn add next@latest react@latest react-dom@latest eslint-config-next@latest

After updating, confirm the installed versions:

npx next --version

Step 2: Update next.config.js

Check your next.config.js file for deprecated options and update them according to the latest Next.js documentation.

Example:

const nextConfig = {
  experimental: {
    appDir: true,
    optimizeCss: true,
    optimizeFonts: true,
  },
  images: {
    domains: ['yourdomain.com'],
  },
};

module.exports = nextConfig;

Ensure you remove any deprecated settings and replace them with recommended configurations.

Step 3: Test Your Application

After upgrading, run the development server to check for any issues:

npm run dev

or

yarn dev

Check the console output for warnings and errors. Pay attention to API routes, middleware changes, and deprecated features.

Step 4: Migrate API Routes to App Router

Next.js 15 enhances API routing. If you're using the Pages Router for API endpoints, consider migrating to the App Router.

Example Migration

Before (Pages Router)

// pages/api/hello.js
export default function handler(req, res) {
  res.status(200).json({ message: "Hello from API!" });
}

After (App Router)

// app/api/hello/route.js
export function GET() {
  return Response.json({ message: "Hello from API!" });
}

This change improves performance and enables better data-fetching strategies.

Step 5: Enable and Optimize Turbopack

Turbopack is now stable in Next.js 15 and significantly improves build speeds.

Enable it in package.json:

{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

Run the development server to confirm the improvements:

npm run dev

Step 6: Deploy the Upgraded App

Once tested locally, deploy the app to your preferred hosting provider such as Vercel or Netlify.

git add .
git commit -m "Upgrade to Next.js 15"
git push origin main

Deploy the updated version using Vercel:

vercel --prod

Common Issues & Troubleshooting

Issue 1: Styles Not Loading

• Ensure CSS imports are correctly placed in layout.js for the App Router.
• Check if optimizeCss is enabled in next.config.js.

Issue 2: API Routes Returning 404

• Ensure all API endpoints follow the new App Router format.
• Restart the development server after making changes.

Issue 3: Performance Drops

• Review network requests in Chrome DevTools.
• Enable caching optimizations in next.config.js.

Conclusion

Upgrading to Next.js 15 unlocks powerful new features, improved performance, and a better developer experience. Following this guide ensures a smooth transition while leveraging the latest capabilities.

For more details, refer to the official Next.js 15 release notes: Next.js 15 Documentation.

By carefully updating dependencies, testing thoroughly, and leveraging new features like Turbopack and the App Router, you can make the most out of this major upgrade.