A← Index

Migrating a production app to Next.js

How I moved an education platform from CRA to Next.js while continuing to ship features.

Tags
Next.js React Performance Migration

IOverview

I led the migration of a production education platform from Create React App (CRA) to Next.js 14 at Qilin Labs. The application served 20K+ registered users and had more than 200 components across 50+ routes. A dependency upgrade prompted us to review the application’s performance and tooling.

This article covers the migration sequence, routing and data-fetching changes, and the results recorded during the project.

IIThe Problem

CRA helped the team start quickly. As the application grew, bundle size, public-page rendering, and development tooling required more attention.

Bundle Size Had Gotten Out of Control

Our main bundle had reached 2.4 MB gzipped, and First Contentful Paint was 4.2 seconds in our measurements. Adding React.lazy and Suspense helped, but routes still loaded a large shared chunk. We needed to review how the application split and loaded code.

SEO Was Non-Existent

The dashboard did not need search visibility, but the public pages did. Maintaining metadata and prerendering through react-helmet and a separate service added work to our deployment setup.

Developer Experience Was Deteriorating

Cold starts took more than 45 seconds in our setup, and some hot updates required a full reload. We also maintained a separate Express service for backend-for-frontend endpoints. These tools and custom scripts made the project harder to maintain.

IIIThe Approach

The application remained in active development, so we moved routes incrementally. Next.js pages ran alongside the CRA application while the team continued to ship features.

Phase 1: Parallel Setup

We added a Next.js 14 application in apps/next-app/ and moved reusable components, hooks, and utilities into packages/shared/. Both applications could import that package during the transition.

project/
  packages/
    shared/          # Components, hooks, utils
      components/
      hooks/
      utils/
  apps/
    legacy-cra/      # Existing CRA app
    next-app/        # New Next.js app
  package.json       # Workspace root

A reverse proxy routed requests between the applications by URL. Migrated pages went to Next.js; routes that had not moved stayed on CRA.

Phase 2: Route-by-Route Migration

We migrated routes in order of impact: public-facing pages first (marketing, docs, reports), then high-traffic dashboard pages, then everything else. For each route, the process was:

  • Create the Next.js route and choose how it should load data. Use generateStaticParams where known dynamic route parameters can be generated ahead of time.
  • Move the route's components from apps/legacy-cra/ to packages/shared/ if they weren't already shared
  • Add the "use client" directive to components that needed browser APIs or React state
  • Update the proxy config to route the URL to Next.js
  • Verify in staging, then ship

Phase 3: Data Fetching Overhaul

The CRA application fetched data on the client with useEffect, fetch, and React Query. We moved initial data fetching to the server where the page requirements supported it.

We used server components for request-time data and static generation for pages that changed less often. revalidatePath handled on-demand invalidation. React Query remained responsible for client-side mutations and optimistic updates.

// Before: Client-side fetching in CRA
function DashboardPage() {
  const { data, isLoading } = useQuery({
    queryKey: ['dashboard'],
    queryFn: () => fetch('/api/dashboard').then(r => r.json())
  });

  if (isLoading) return <Skeleton />;
  return <Dashboard data={data} />;
}

// After: Server component in Next.js
async function DashboardPage() {
  const data = await getDashboardData();
  return <Dashboard data={data} />;
}

Phase 4: Handling Client-Side Routing

During the transition, navigation could cross between React Router and the Next.js router. We used standard <a> links for those crossings. As routes moved to Next.js, fewer links needed a full-page navigation.

IVResults

We migrated the application over 10 weeks while keeping it available. The project recorded the following results:

60%
Lower First Contentful Paint
70%
Smaller bundle size
90+
Lighthouse score

Performance Breakdown

First Contentful Paint dropped from 4.2s to 1.6s. The main bundle went from 2.4 MB to 720 KB gzipped. The migration changed code splitting and initial rendering so users received page content earlier.

Recorded Lighthouse scores improved from a 58–62 range to 90+. Public pages also gained server-rendered content, metadata, and structured data. We observed those pages appearing in search results within two weeks.

Developer Experience

Our cold-start measurements dropped from more than 45 seconds to under 3 seconds with Turbopack. We moved the backend-for-frontend endpoints into API routes and retired the separate Express service.

VKey Takeaways

Move one route at a time

The proxy let us deploy and review individual routes. We used that rollback scope when a migrated route exposed a data-fetching edge case.

Extract shared code first

Extracting shared code first separated component work from route migration. Each route could then focus on data fetching and page behavior. Components tied to build-specific loaders needed attention before they could be shared.

Server components change how you think about data

Moving initial data fetching to the server changed our component boundaries, error handling, and loading states. We separated server and client responsibilities where the application needed both.

Measure before, during, and after

We used Real User Monitoring with Web Vitals to follow production performance during the migration. Lighthouse supplied separate lab scores. These sources answer different questions and should be read separately.

An incremental migration gives each route a smaller review and rollback scope. Baseline measurements help show whether the changes are useful.

SignedArjun