19 February 2026 · 5 min read
Migrating a production app to Next.js
How I moved an education platform from CRA to Next.js while continuing to ship features.
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
generateStaticParamswhere known dynamic route parameters can be generated ahead of time. - Move the route's components from
apps/legacy-cra/topackages/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:
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.