Static to Dynamic: Migrating Gatsby/CRA to Next.js 15 (Step-by-Step)

Introduction

Next.js 15 delivers the full-stack React experience teams have wanted: React Server Components (RSC), the App Router, Incremental Static Regeneration (ISR), edge rendering, first-class image & font optimization, and a powerful Metadata API for SEO. If you’re running a Gatsby or Create React App (CRA) site and need faster builds, dynamic personalization, or better Core Web Vitals, this step-by-step migration guide will get you to Next.js 15 with minimal friction—and maximum long-term wins.

We’ll cover planning, project bootstrapping, routing differences, data fetching, SEO and redirects, styling and assets, testing, and CI/CD. You’ll learn how to map Gatsby GraphQL queries or CRA client-only fetches into server-first patterns that ship HTML quickly, reduce client JS, and preserve (or improve) rankings.

1) Plan Your Migration: Inventory, Priorities, and Cutover

Start with an audit. The right plan reduces risk and keeps organic traffic steady.

• Inventory pages & routes: List URLs, templates, and dynamic parameters (e.g., /blog/[slug]).
• Data sources: Note CMSes, Markdown, REST/GraphQL endpoints, environment variables, and build steps.
• SEO assets: Titles, meta descriptions, canonical tags, hreflang, structured data, sitemaps, robots rules.
• Performance: Largest media, fonts, third-party scripts; identify LCP/INP/CLS offenders.
• Cutover strategy: Big bang vs. incremental (subpaths, reverse proxy, or DNS split by route).

Tip: Migrate the highest-value, low-complexity paths first (e.g., marketing pages, docs, blog), then complex app areas.

2) Create the Next.js 15 App (App Router + RSC)

npx create-next-app@latest next15-migrate --ts --eslint
cd next15-migrate
# App Router is default; ensure /app exists
tree -L 2 app

Next.js 15 is RSC-first. Keep components server by default, add "use client" only where interactivity is needed. This reduces bundle size and improves Time to Interactive.

3) Routing Differences: Gatsby/CRA → App Router

Gatsby maps files in src/pages, and can create pages programmatically in gatsby-node. CRA relies on react-router. In Next.js 15, use App Router with nested segments and route groups. Dynamic params are folder names in brackets.

Gatsby:  src/pages/blog/{slug}.js
CRA:     <Route path="/blog/:slug" element={...} />
Next 15: app/(marketing)/blog/[slug]/page.tsx

// app/(marketing)/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import { getPostBySlug } from "@/lib/cms";

export const dynamic = "force-static"; // Static by default, opt into ISR via revalidate
export const revalidate = 600; // 10min ISR

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await getPostBySlug(params.slug);
  if (!post) notFound();
  return (
    <article>
      <h1>{post.title}</h1>
      <p className="lead">{post.excerpt}</p>
      <div dangerouslySetInnerHTML={{ __html: post.html }} />
    </article>
  );
}

Use Route Groups like app/(marketing) to separate SEO’d content from app dashboards where you might set robots: noindex.

4) Data Fetching: From Gatsby GraphQL/StaticQuery & CRA Fetch to RSC

Gatsby relies on GraphQL at build time. CRA fetches on the client (CSR). In Next.js 15, fetch data on the server using RSC and control caching/ISR precisely.

// lib/cms.ts (RSC-friendly fetch)
export async function getPostBySlug(slug: string) {
  const res = await fetch(`https://cms.example.com/posts/${slug}`, {
    next: { revalidate: 600, tags: [`post:${slug}`] }, // ISR + on-demand hooks
  });
  if (!res.ok) return null;
  return res.json();
}

For Gatsby Markdown, read files at build time or use a headless CMS. For CRA APIs previously called client-side, move them server-side in the route and pass minimal props to client components.

On-demand revalidation: trigger from your CMS on publish to refresh the cache immediately.

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";

export async function POST(req: Request) {
  const { tag, secret } = await req.json();
  if (secret !== process.env.REVALIDATE_TOKEN) return new Response("Unauthorized", { status: 401 });
  revalidateTag(tag);
  return Response.json({ revalidated: true });
}

5) SEO Migration: Metadata API, Canonicals, Hreflang, Structured Data

Replace Gatsby plugins or CRA head management with the Metadata API. Co-locate meta with the route so it stays in sync with content.

/// app/(marketing)/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { getPostBySlug } from "@/lib/cms";

export async function generateMetadata(
  { params }: { params: { slug: string } }
): Promise<Metadata> {
  const post = await getPostBySlug(params.slug);
  const url = `https://example.com/blog/${params.slug}`;
  return {
    title: post?.seoTitle ?? post?.title ?? "Blog",
    description: post?.seoDescription ?? post?.excerpt,
    alternates: {
      canonical: url,
      languages: { "en": url, "hi": url.replace("/blog/", "/hi/blog/") }
    },
    openGraph: {
      title: post?.title,
      description: post?.excerpt,
      url,
      type: "article",
      images: post?.ogImage ? [{ url: post.ogImage, width: 1200, height: 630 }] : []
    },
    robots: { index: true, follow: true }
  };
}

Render JSON-LD server-side to ensure parsers see it in the initial HTML.

// app/(marketing)/blog/[slug]/Schema.tsx
export default function ArticleSchema({ post }: { post: any }) {
  const data = {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: post.title,
    description: post.excerpt,
    datePublished: post.date,
    dateModified: post.updatedAt ?? post.date,
    author: [{ "@type": "Person", name: post.author.name }],
    image: [post.ogImage]
  };
  return (<script type="application/ld+json">{JSON.stringify(data)}</script>);
}

6) URLs, Redirects, and Canonicalization

Preserve existing URLs where possible. If paths must change, implement 301 redirects and normalize noisy query params using middleware.ts.

// next.config.ts (static redirects)
const nextConfig = {
  async redirects() {
    return [
      { source: "/old-blog/:slug/", destination: "/blog/:slug", permanent: true },
    ];
  },
};
export default nextConfig;

// middleware.ts (canonicalize UTM, trailing slash policy)
import { NextResponse } from "next/server";
export function middleware(req: Request) {
  const url = new URL(req.url);
  ["utm_source","utm_medium","utm_campaign","gclid"].forEach(p => url.searchParams.delete(p));
  if (!url.pathname.endsWith("/")) { url.pathname += "/"; return NextResponse.redirect(url); }
  return NextResponse.next();
}

Regenerate sitemaps with App Router so search engines discover Next pages quickly.

// app/sitemap.ts
import { getAllSlugs } from "@/lib/cms";
export default async function sitemap() {
  const slugs = await getAllSlugs();
  const base = "https://example.com";
  return slugs.map((s) => ({ url: `${base}/blog/${s}`, changeFrequency: "weekly", priority: 0.8 }));
}

7) Images & Fonts: Next.js Optimization for LCP/CLS

Replace Gatsby image plugins or CRA image tags with Next.js <Image /> and Google Fonts integration for better LCP and CLS.

import Image from "next/image";
import { Inter } from "next/font/google";
const inter = Inter({ subsets: ["latin"], display: "swap" });

export default function Hero() {
  return (
    <section className={inter.className}>
      <Image src="/hero.jpg" alt="Next.js migration" width={1280} height={720} priority />
      <h1>Migrate to Next.js 15</h1>
    </section>
  );
}

Always set width/height to lock layout, preload the hero image, and lazy-load below-the-fold media. For self-hosted fonts, preload the critical subset.

8) Styling, State, and Client Components

Bring your existing styling library (Tailwind, CSS Modules, CSS-in-JS). Keep most UI server-rendered; mark interactive islands with "use client". Avoid global state for public marketing routes; prefer local state or server data.

"use client";
import * as React from "react";
// Client-only interactive widget
export function NewsletterForm() {
  const [email, setEmail] = React.useState("");
  return (
    <form action="/api/subscribe" method="post">
      <input name="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <button type="submit">Subscribe</button>
    </form>
  );
}

Server Components fetch and render content; client components handle events and animations.

9) Environment, Config, and Build Pipeline

Map your Gatsby/CRA env usage to Next env rules (NEXT_PUBLIC_* for client). Validate at build time.

# .env
CMS_URL=https://cms.example.com
NEXT_PUBLIC_ANALYTICS_ID=abc123

Use edge runtime where latency matters (geo redirects, A/B cookies) and Node runtime for heavy server work.

10) Testing & Quality Gates: Keep Confidence During Migration

Lock behaviors with unit, integration, and e2e tests. If you’re migrating a large site, snapshot legacy HTML where possible and compare key templates.

# .github/workflows/ci.yml (excerpt)
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20" }
      - run: npm ci
      - run: npm run lint && npm run typecheck
      - run: npm run test -- --coverage
      - run: npx playwright install --with-deps && npm run e2e
      - run: npm run lighthouse:ci

Add accessibility checks (axe/Pa11y), and block PRs that regress LCP/INP/CLS beyond budgets.

11) Deploy, Observe, and Iterate

Deploy to a platform with first-class Next.js support and global edge network. Monitor real-user metrics (RUM), error rates, and crawl stats. Use on-demand revalidation webhooks from your CMS so editors see changes instantly without full rebuilds.

• Observability: Web Vitals in production, 404/500 logs, slow API traces.
• SEO monitoring: Crawl new Next routes, verify canonicals and hreflang, watch index coverage.
• Perf budgets: Bundle size limits, image weight caps, third-party script guards.

12) Common Pitfalls (and How to Fix Them)

• Hydration mismatches: Split client logic; avoid reading browser-only APIs in RSC. Move such code into "use client" components.
• Lost redirects: Mirror every Gatsby/CRA redirect in next.config.ts and middleware.ts. Verify with a crawl.
• Slow images: Missing width/height or priority flags; convert to Next Image.
• Duplicate content: Normalize trailing slashes, query params, and add consistent canonicals via Metadata API.
• Client-only data: Move fetches server-side to lower JS cost and improve SEO.

13) Quick Checklist: Gatsby/CRA → Next.js 15

• ✅ App Router created; routes mapped (static/dynamic) with ISR where suitable
• ✅ Metadata API replacing head management; JSON-LD rendered server-side
• ✅ All legacy redirects implemented; sitemap & robots updated
• ✅ Images/fonts optimized; LCP asset preloaded; CLS guarded
• ✅ Data moved to server; client islands only for interactivity
• ✅ On-demand revalidation hooked to CMS
• ✅ Tests, a11y checks, Lighthouse budgets in CI
• ✅ Observability & RUM in place; post-cutover crawl verified

Conclusion

Migrating from Gatsby or Create React App to Next.js 15 unlocks server-first rendering, modern caching, and platform features that make sites faster, more indexable, and easier to maintain. By mapping routes to the App Router, moving fetches into React Server Components, enabling ISR, and using the Metadata API, you’ll deliver HTML quickly, reduce JS on the client, and protect Core Web Vitals.

Adopt an incremental cutover if needed, start with high-impact pages, and validate via redirects, structured data, and RUM. With this playbook, your team can modernize the stack without sacrificing SEO or developer velocity—and set the foundation for personalization, edge logic, and rapid iteration in 2025 and beyond.