Next.js 16 + React 19 Complete Migration Guide

// BEFORE: Next.js 15 Pages Router (pages/users/[id].tsx)
// This file pattern is REMOVED in Next.js 16

// export async function getServerSideProps(context) {
//   const { id } = context.params;
//   const user = await fetch(`https://api.example.com/users/${id}`);
//   return { props: { user: await user.json() } };
// }
//
// export default function UserProfile({ user }) {
//   return <div><h1>{user.name}</h1></div>;
// }

// AFTER: Next.js 16 App Router (app/users/[id]/page.tsx)
// Server Component by default — no 'use client' needed

interface User {
  id: string;
  name: string;
  email: string;
}

// This is a Server Component — it runs on the server, not the browser
// The function is async — data fetching happens at the component level
export default async function UserProfile({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  // params is a Promise in Next.js 16 — must await it
  const { id } = await params;

  const response = await fetch(`https://api.example.com/users/${id}`);
  const user: User = await response.json();

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

// Generate metadata from the same data — no separate getServerSideProps
export async function generateMetadata({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const response = await fetch(`https://api.example.com/users/${id}`);
  const user: User = await response.json();

  return {
    title: `${user.name} - Profile`,
    description: `Profile page for ${user.name}`,
  };
}

#!/usr/bin/env bash
# io.thecodeforge: Pre-migration check for Next.js 15 -> 16
# Run this BEFORE upgrading to catch breaking changes early

set -euo pipefail

echo "=== Next.js 16 Migration Pre-Check ==="
echo ""

ERRORS=0

# Check 1: Babel config files — must be removed
echo "[1/6] Checking for Babel config files..."
BABEL_FILES=$(find . -maxdepth 2 -name '.babelrc' -o -name 'babel.config.*' 2>/dev/null | grep -v node_modules || true)
if [ -n "$BABEL_FILES" ]; then
  echo "  FAIL: Babel config found — Next.js 16 ignores these silently"
  echo "$BABEL_FILES" | sed 's/^/    /'
  ERRORS=$((ERRORS + 1))
else
  echo "  PASS: No Babel config files found"
fi

# Check 2: Pages Router directory
echo "[2/6] Checking for pages/ directory..."
if [ -d "pages" ]; then
  echo "  FAIL: pages/ directory exists — must migrate to app/"
  echo "  Files found:"
  find pages -name '*.tsx' -o -name '*.ts' | head -10 | sed 's/^/    /'
  ERRORS=$((ERRORS + 1))
else
  echo "  PASS: No pages/ directory found"
fi

# Check 3: next.config.js for deprecated options
echo "[3/6] Checking next.config.js for deprecated options..."
if [ -f "next.config.js" ] || [ -f "next.config.mjs" ]; then
  CONFIG_FILE=$(ls next.config.* 2>/dev/null | head -1)
  DEPRECATED=$(grep -E 'experimental.appDir|swcMinify|images.domains' "$CONFIG_FILE" 2>/dev/null || true)
  if [ -n "$DEPRECATED" ]; then
    echo "  FAIL: Deprecated config options found:"
    echo "$DEPRECATED" | sed 's/^/    /'
    ERRORS=$((ERRORS + 1))
  else
    echo "  PASS: No deprecated config options found"
  fi
fi

# Check 4: React 18 patterns that break in React 19
echo "[4/6] Checking for React 18 breaking patterns..."
REACT18_BREAKS=$(grep -rn 'forwardRef\|useContext.*createContext\|ReactDOM.render' app/ src/ --include='*.tsx' --include='*.ts' 2>/dev/null | head -10 || true)
if [ -n "$REACT18_BREAKS" ]; then
  echo "  WARN: Patterns that may need updating for React 19:"
  echo "$REACT18_BREAKS" | sed 's/^/    /'
else
  echo "  PASS: No obvious React 18 breaking patterns found"
fi

# Check 5: CSS-in-JS with Babel dependency
echo "[5/6] Checking for CSS-in-JS with Babel dependency..."
CSS_IN_JS=$(grep -E 'emotion|styled-components|linaria' package.json 2>/dev/null || true)
if [ -n "$CSS_IN_JS" ]; then
  echo "  WARN: CSS-in-JS library detected — verify Next.js 16 compatibility"
  echo "$CSS_IN_JS" | sed 's/^/    /'
else
  echo "  PASS: No Babel-dependent CSS-in-JS libraries found"
fi

# Check 6: Node.js version
echo "[6/6] Checking Node.js version..."
NODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1)
if [ "$NODE_VERSION" -lt 18 ]; then
  echo "  FAIL: Node.js $(node -v) detected — Next.js 16 requires Node 18+"
  ERRORS=$((ERRORS + 1))
else
  echo "  PASS: Node.js $(node -v) is compatible"
fi

echo ""
if [ $ERRORS -gt 0 ]; then
  echo "RESULT: $ERRORS blocking issues found — fix before upgrading"
  exit 1
else
  echo "RESULT: All checks passed — safe to upgrade"
  exit 0
fi

import * as React from 'react';

// BEFORE: React 18 — forwardRef wrapper required
// import { forwardRef } from 'react';
//
// interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
//   variant: 'primary' | 'secondary';
// }
//
// const Button = forwardRef<HTMLButtonElement, ButtonProps>(
//   ({ variant, children, ...props }, ref) => {
//     return (
//       <button
//         ref={ref}
//         className={variant === 'primary' ? 'btn-primary' : 'btn-secondary'}
//         {...props}
//       >
//         {children}
//       </button>
//     );
//   }
// );
// Button.displayName = 'Button';

// AFTER: React 19 — ref is a regular prop, no forwardRef needed
interface ButtonProps extends React.ComponentPropsWithoutRef<'button'> {
  variant: 'primary' | 'secondary';
  ref?: React.Ref<HTMLButtonElement>;
}

function Button({ variant, ref, children, ...props }: ButtonProps) {
  return (
    <button
      ref={ref}
      className={variant === 'primary' ? 'btn-primary' : 'btn-secondary'}
      {...props}
    >
      {children}
    </button>
  );
}

export { Button };

// ---

// BEFORE: React 18 — useEffect + useState for data fetching
// function UserProfile({ userId }: { userId: string }) {
//   const [user, setUser] = useState(null);
//   const [loading, setLoading] = useState(true);
//
//   useEffect(() => {
//     fetch(`/api/users/${userId}`)
//       .then(res => res.json())
//       .then(data => { setUser(data); setLoading(false); });
//   }, [userId]);
//
//   if (loading) return <Spinner />;
//   return <div>{user.name}</div>;
// }

// AFTER: React 19 — use() hook with Suspense
import { use } from 'react';

function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise); // Suspends until resolved
  return <div>{user.name}</div>;
}

// Parent wraps in Suspense:
// <Suspense fallback={<Spinner />}>
//   <UserProfile userPromise={fetchUser(userId)} />
// </Suspense>

// Server Actions file — all exported functions run on the server
'use server';

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { z } from 'zod';

// Validation schema — always validate server-side, never trust client input
const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1).max(10000),
  categoryId: z.string().uuid(),
});

export async function createPost(formData: FormData) {
  // 1. Validate input — Server Actions receive FormData, not JSON
  const raw = {
    title: formData.get('title') as string,
    content: formData.get('content') as string,
    categoryId: formData.get('categoryId') as string,
  };

  const parsed = CreatePostSchema.safeParse(raw);
  if (!parsed.success) {
    return {
      error: 'Validation failed',
      fieldErrors: parsed.error.flatten().fieldErrors,
    };
  }

  // 2. Perform the mutation — this runs on the server
  const post = await db.post.create({
    data: parsed.data,
  });

  // 3. Revalidate the cache — the posts list page updates
  revalidatePath('/posts');

  // 4. Redirect to the new post
  redirect(`/posts/${post.id}`);
}

export async function deletePost(postId: string) {
  await db.post.delete({ where: { id: postId } });
  revalidatePath('/posts');
  return { success: true };
}

import { Suspense } from 'react';
import { Skeleton } from '@/components/ui/skeleton';

// Each section fetches its own data
// The page shell renders in ~200ms regardless of data latency

async function MetricsSection() {
  // This fetch takes 800ms — but the page shell renders in 200ms
  const metrics = await fetch('https://api.example.com/metrics', {
    next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
  }).then(res => res.json());

  return (
    <div className="grid grid-cols-4 gap-4">
      {metrics.map((m: { label: string; value: string }) => (
        <div key={m.label} className="rounded-lg border p-4">
          <p className="text-sm text-muted-foreground">{m.label}</p>
          <p className="text-2xl font-bold">{m.value}</p>
        </div>
      ))}
    </div>
  );
}

async function RecentPostsSection() {
  // This fetch takes 1200ms — but it does not block MetricsSection
  const posts = await fetch('https://api.example.com/posts?limit=5', {
    next: { revalidate: 30 },
  }).then(res => res.json());

  return (
    <div className="space-y-4">
      {posts.map((p: { id: string; title: string }) => (
        <div key={p.id} className="rounded-lg border p-4">
          <h3 className="font-medium">{p.title}</h3>
        </div>
      ))}
    </div>
  );
}

async function ActivityFeedSection() {
  // This fetch takes 2000ms — but it streams in last, not blocking anything
  const activity = await fetch('https://api.example.com/activity', {
    cache: 'no-store', // Always fresh — no caching
  }).then(res => res.json());

  return (
    <div className="space-y-2">
      {activity.map((a: { id: string; message: string }) => (
        <div key={a.id} className="text-sm text-muted-foreground">
          {a.message}
        </div>
      ))}
    </div>
  );
}

// The page component orchestrates streaming — shell renders in ~200ms
export default function DashboardPage() {
  return (
    <div className="space-y-8 p-8">
      <h1 className="text-3xl font-bold">Dashboard</h1>

      {/* Each Suspense boundary streams independently */}
      <Suspense fallback={<Skeleton className="h-32 w-full" />}>
        <MetricsSection />
      </Suspense>

      <Suspense fallback={<Skeleton className="h-64 w-full" />}>
        <RecentPostsSection />
      </Suspense>

      <Suspense fallback={<Skeleton className="h-96 w-full" />}>
        <ActivityFeedSection />
      </Suspense>
    </div>
  );
}

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { render, screen, waitFor } from '@testing-library/react';
import { Suspense } from 'react';

// Layer 1: Build validation — catch silent failures before runtime
// These run in CI before the migration is merged

describe('Migration Build Validation', () => {
  it('should not have .babelrc in project root', () => {
    // This test runs as a pre-build check
    // If .babelrc exists, Babel plugins are silently ignored
    const fs = require('fs');
    const hasBabelRc = fs.existsSync('.babelrc');
    const hasBabelConfig = fs.existsSync('babel.config.js') || fs.existsSync('babel.config.mjs');
    expect(hasBabelRc || hasBabelConfig).toBe(false);
  });

  it('should not have pages/ directory', () => {
    const fs = require('fs');
    expect(fs.existsSync('pages')).toBe(false);
  });

  it('should not use forwardRef in any component', async () => {
    // Grep for forwardRef usage — all should be migrated
    const { execSync } = require('child_process');
    const result = execSync(
      'grep -rn "forwardRef" app/ src/ --include="*.tsx" --include="*.ts" || true',
      { encoding: 'utf-8' }
    );
    expect(result.trim()).toBe('');
  });
});

// Layer 2: Component validation — verify React 19 patterns

describe('React 19 Component Patterns', () => {
  it('Button component accepts ref as a regular prop', () => {
    const ref = { current: null };
    // This should work without forwardRef in React 19
    render(<button ref={ref}>Click me</button>);
    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
  });

  it('Server Component renders async data without useEffect', async () => {
    // Mock the fetch
    global.fetch = vi.fn().mockResolvedValue({
      json: () => Promise.resolve({ name: 'Test User', email: 'test@example.com' }),
    });

    // Server Component pattern — async function, no useEffect
    async function UserProfile() {
      const user = await fetch('/api/users/1').then(r => r.json());
      return <div data-testid="user-name">{user.name}</div>;
    }

    render(
      <Suspense fallback={<div data-testid="loading">Loading...</div>}>
        <UserProfile />
      </Suspense>
    );

    // Fallback renders first
    expect(screen.getByTestId('loading')).toBeInTheDocument();

    // Data resolves, content replaces fallback
    await waitFor(() => {
      expect(screen.getByTestId('user-name')).toHaveTextContent('Test User');
    });
  });
});

// Layer 3: Routing validation — verify all routes resolve

describe('App Router Route Validation', () => {
  it('should not reference pages/ import paths', () => {
    const { execSync } = require('child_process');
    const result = execSync(
      'grep -rn "from.*pages/" app/ src/ --include="*.tsx" --include="*.ts" || true',
      { encoding: 'utf-8' }
    );
    expect(result.trim()).toBe('');
  });

  it('should not use getServerSideProps or getStaticProps', () => {
    const { execSync } = require('child_process');
    const result = execSync(
      'grep -rn "getServerSideProps\|getStaticProps" app/ src/ --include="*.tsx" --include="*.ts" || true',
      { encoding: 'utf-8' }
    );
    expect(result.trim()).toBe('');
  });
});