Incremental React and Next.js Migration for Legacy PHP or .NET
Modernise legacy PHP or .NET systems page by page with React or Next.js using proven integration patterns, API gateways, and incremental deployment strategies.
Most enterprise rewrites fail not because the new technology is wrong, but because the organisation tries to replace everything at once. A React or Next.js incremental adoption strategy lets teams modernise one page, one feature, one customer journey at a time, while the legacy PHP or .NET system keeps running and earning revenue. The approach is not new. What is still poorly understood is the specific wiring: where the reverse proxy sits, how the API gateway federates old and new backends, and which deployment topology keeps both systems stable.
Get an architecture review for your legacy-to-React migration plan.
Why “Big Bang” Rewrites Keep Failing
Martin Fowler coined the term “Strangler Fig Application” over two decades ago, yet enterprises still attempt full rewrites. The pattern is predictable. A team spends twelve to eighteen months rebuilding, feature parity remains elusive, the business changes requirements mid-flight, and the project either ships late with missing functionality or gets cancelled outright.
Incremental adoption sidesteps this entirely. You route individual URLs to a new React or Next.js application while every other route continues to hit the existing PHP (Laravel, WordPress, Symfony) or .NET (ASP.NET MVC, Razor Pages) stack. Users do not notice the transition. Neither does Google, provided you handle canonical URLs and redirects correctly.
The real question is not whether to adopt incrementally. It is how to set up the infrastructure so that two runtimes coexist without doubling your operational burden. That infrastructure has three layers: the routing layer, the API layer, and the deployment layer.
The Routing Layer: Reverse Proxy as the Seam
The reverse proxy is the single most important piece of the incremental architecture. It sits in front of both the legacy application and the new Next.js (or React with a custom server) application, routing requests based on path, hostname, cookie, or header.
NGINX, Caddy, and cloud-native load balancers (AWS ALB path-based routing, Azure Front Door, Cloudflare Workers) all work. The choice depends on where your legacy system already runs. If your .NET application is on Azure App Service, Azure Front Door is the path of least resistance. If you are on AWS, an ALB with target groups pointed at separate ECS services or EC2 instances keeps things simple.
The routing rules should live in version control, not in a dashboard someone clicks through. Treat them as code. A typical NGINX snippet for the strangler pattern looks like this: define an upstream for the legacy PHP-FPM pool, another upstream for the Next.js Node process, and route /products/* to Next.js while sending everything else to PHP. As you migrate more pages, you add more location blocks. The legacy upstream slowly starves of traffic.
The reverse proxy is not just a traffic splitter. It is the organisational boundary between the old team’s deploy cadence and the new team’s deploy cadence. Get it wrong, and a deploy on one side breaks the other.
One subtlety: session handling. If the legacy system uses server-side sessions (common in older .NET and PHP stacks), you need the proxy to route session-bearing requests consistently. Sticky sessions at the load balancer, or migrating to a shared session store like Redis, solves this. Do not skip this step. Users who toggle between legacy and modern pages mid-session will hit authentication walls otherwise.
API Gateway Decisions
Your new React front end needs data. That data lives in the legacy system’s database, behind its own controllers and business logic. You have three options, each with different trade-offs.
For most teams starting an incremental migration, option one gets you moving. Option two becomes necessary once you have three or four migrated pages hitting the legacy API in ways the original code was not designed for. Option three is justified when you have multiple consuming clients (web, mobile, partner integrations) and need centralised policy enforcement.
Whichever path you choose, version your API contracts from day one. URL versioning (/api/v1/products) is blunt but unambiguous. Header-based versioning is cleaner but harder to debug in production. Pick one and stick with it. Changing versioning strategies mid-migration creates exactly the kind of coordination overhead you are trying to avoid.
Expose legacy endpoints directly:
Add a lightweight JSON API to the existing PHP or .NET application. Laravel makes this straightforward with API resource controllers. ASP.NET can expose Web API controllers alongside MVC views. This is the fastest approach, but it couples the new front end to legacy code that you eventually want to retire.
Build a Backend-for-Frontend (BFF):
Stand up a thin Node.js or .NET service that calls the legacy system’s database or internal services, reshapes the data for the React front end, and handles authentication translation. This is more work upfront but gives the new front end a stable contract that does not break when legacy internals change. If you are choosing between Node.js and PHP for this middle layer, the decision often comes down to team expertise and latency requirements.
Use an API gateway to federate both:
Tools like Kong, AWS API Gateway, or Azure API Management sit between the front end and multiple backends. The gateway handles rate limiting, authentication, and routing, sending /api/products to the new service and /api/orders to the legacy system. This is the cleanest separation, but it adds latency and operational complexity.
SSR, SSG, or Client-Side: Picking the Right Rendering Model per Page
Next.js gives you the luxury of choosing rendering strategy per route. That flexibility matters in an incremental migration because not every page has the same performance or SEO requirement.
Product listing pages that Google needs to crawl deserve server-side rendering or static generation. An authenticated dashboard behind a login can render entirely on the client. A marketing landing page with infrequent content changes is a perfect candidate for ISR (Incremental Static Regeneration) with a revalidation interval measured in minutes.
The mistake teams make is applying a single rendering strategy across all migrated pages. That leads to either unnecessary server load (SSR for everything) or poor SEO (client rendering for everything). Map each page to its rendering model before you write the first component.
Deployment Topology That Keeps Both Systems Stable
Running two application runtimes in production means two deployment pipelines, two sets of health checks, and two scaling profiles. Here is how to keep this manageable.
Containerise the Next.js application from the start, even if the legacy system is not containerised. A Docker image running next start behind the reverse proxy gives you portability across AWS ECS, Azure Container Apps, Google Cloud Run, or a plain VM with Docker installed. The legacy system can stay exactly where it is.
CI/CD pipelines should be independent. A deploy to the Next.js service must not require a deploy to the legacy system, and vice versa. If both pipelines share a single deployment artifact or a single approval gate, you have re-coupled the systems at the process level. Keep them separate. Coordinate through the API contract, not through synchronised releases.
The goal of incremental adoption is independent deployability. If you cannot ship a change to the new front end without touching the legacy system, you have not actually decoupled anything.
For teams managing both web and mobile surfaces from a shared codebase, the question of monorepo versus separate codebases comes up quickly. In most incremental migrations, keeping the new front end in its own repository avoids permission and build-time entanglement with legacy code. A monorepo becomes attractive later, once the legacy system is fully retired and you want to share components across web and mobile.
Shared Layout, Auth, and Design System: The Glue That Makes It Seamless
Users should not perceive a seam between legacy pages and migrated pages. That requires three things to be consistent: navigation and footer, authentication state, and visual design.
For navigation, the simplest approach is an independently deployed header/footer served as static HTML fragments that both systems include. Some teams use micro-frontend composition for this, but a static include via server-side includes (SSI) or an edge-side include (ESI) at the CDN layer is far simpler and performs better.
Authentication is trickier. If the legacy system uses cookie-based sessions, the new application needs to validate the same cookie. Shared-domain cookies with a common auth service (OAuth2 or OpenID Connect via a provider like Auth0 or Azure AD B2C) give you a clean handoff. The legacy system and the Next.js application both validate tokens from the same issuer. Users log in once.
Design consistency comes from a shared design system, ideally as a versioned npm package that the React application consumes. The legacy system gets the same visual treatment through compiled CSS from the same design tokens. This is where teams building large-scale enterprise sites invest early, because inconsistent UI between old and new pages erodes user trust and internal stakeholder confidence in the migration.
Measuring Progress and Knowing When to Cut Over
Track three metrics per migrated page: Core Web Vitals (LCP, CLS, INP), error rate compared to the legacy equivalent, and the percentage of total traffic now served by the new stack. When a page on the new stack matches or beats the legacy page on all three, it is done. When all pages are done, decommission the legacy upstream from the reverse proxy and retire the old codebase.
That last sentence sounds simple. It usually takes longer than the migration itself because someone discovers a forgotten admin panel or an internal tool that still hits the legacy stack. Inventory every route before you start. The routes you do not know about are the ones that delay the cutover by months.
FAQs
Can I use React without Next.js for incremental adoption?
Yes. A plain React SPA behind the reverse proxy works if you do not need server-side rendering or static generation. However, Next.js provides per-route rendering flexibility, built-in API routes for BFF patterns, and image optimisation out of the box. For most enterprise migrations, Next.js reduces the amount of custom infrastructure you need to build.
How do I handle SEO during an incremental migration?
Keep URLs identical between the legacy and migrated versions. The reverse proxy routes traffic by path, so the URL does not change from the user’s or Google’s perspective. Ensure the new pages return the same canonical tags, structured data, and meta information. Monitor Google Search Console for crawl errors after each page cutover.
What if my legacy system uses a relational database that the new front end also needs?
Do not connect the new front end directly to the legacy database. Use an API layer (legacy endpoints, a BFF, or an API gateway) to mediate access. Direct database access from two applications creates schema coupling that makes future changes to either system dangerous.
How long does an incremental migration typically take?
It depends on the number of distinct page templates and the complexity of business logic in the legacy system. A site with ten core templates might migrate in three to six months. A large platform with hundreds of templates and deep server-side logic can take twelve months or more. The advantage of incremental adoption is that each migrated page delivers value immediately rather than waiting for a complete rewrite.
Do I need a micro-frontend framework for this?
Usually not. Micro-frontend frameworks like Module Federation or single-spa solve a different problem: composing multiple front-end applications into a single page. Incremental migration is page-level routing, which a reverse proxy handles without additional framework complexity. Micro-frontends become relevant if you need components from the old and new systems on the same page simultaneously.
Modernise Without the Rewrite Risk
Incremental adoption works when the routing, API, and deployment layers are designed together from the start. We help enterprise teams architect and ship React and Next.js migrations that deliver value page by page.