Modern teams want faster delivery, better SEO, and a stack that scales. This case study shows how I migrated a production PHP app to Next.js (App Router) + Node.js in just three weeks—without breaking URLs, SEO, or user sessions.
Project Goals
- Zero/near-zero downtime during cutover
- URL parity (keep existing slugs and query params) to preserve SEO
- Same or better performance (LCP/TTFB)
- Modern DX (TypeScript, testing, CI/CD)
- Gradual migration using a strangler-fig pattern (old + new side-by-side)
Architecture at a Glance
User ─▶ Nginx/ALB
├─▶ Next.js 15 (App Router, RSC, Edge where useful)
│ ├─▶ API routes (mutations via Server Actions)
│ └─▶ Redis cache (hot reads)
└─▶ PHP legacy (only for routes not yet migrated)
DB: MySQL (via Prisma) Assets: S3 + CloudFront Observability: Sentry + Uptime + Logs
Key idea: route-by-route replacement. Nginx (or middleware) sends traffic to Next.js for migrated paths and to PHP for the rest.
Week-by-Week Plan (3 Weeks)
Week 1 — Discovery, Foundations, and Proxy
Day 1–2: Audit & map
- Inventory URLs, templates, forms, and API endpoints.
- Identify critical flows (login, checkout/contact, search, top landing pages).
- Export MySQL schema and sample data.
- Decide which URLs migrate first (80/20).
Day 3: Environment & repo
- Create monorepo (or separate repos): apps/web (Next.js), infra, and scripts.
- Set up TypeScript, ESLint, Prettier, Husky, and CI (GitHub Actions).
- Configure Prisma against existing MySQL:
npx prisma init
npx prisma db pull # introspect legacy schema
- Add Redis (ElastiCache or Docker) for hot caching.
Day 4: Routing & SEO parity
- Implement App Router structure mirroring legacy slugs:
/app
/[category]
/[slug]
/page.tsx
- Use generateMetadata for titles, OpenGraph, and canonicals:
export async function generateMetadata({ params }) {
const post = await getPost(params.slug);
return { title: post.seoTitle, description: post.seoDesc, alternates: { canonical: `/${post.slug}` } };
}
Day 5: Strangler proxy
- Put Nginx in front; send migrated routes to Next.js, others to PHP:
server {
listen 80;
server_name example.com;
location ~* ^/(blog|products|about) {
proxy_pass http://nextjs:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
}
# fallback to legacy
location / {
proxy_pass http://php_legacy:80;
}
}
- For Vercel/Edge, you can do it in middleware while PHP remains under /legacy:
// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
export function middleware(req: NextRequest) {
const url = new URL(req.url);
const migrated = /^\/(blog|products|about)/.test(url.pathname);
if (!migrated) {
url.hostname = process.env.LEGACY_HOST!; // e.g., legacy.example.com
return NextResponse.rewrite(url);
}
return NextResponse.next();
}
Deliverables end of Week 1:
Working Next.js shell with parity routing for the first set of pages, Nginx proxy in front, Prisma connected, Redis ready.
Week 2 — Feature Parity & Data Flows
Day 6–7: Data layer & caching
- Wrap legacy queries with Prisma services:
// lib/posts.ts
import { prisma } from "./prisma";
import Redis from "ioredis";
const redis = new Redis(process.env.REDIS_URL!);
export async function getPost(slug: string) {
const key = `post:${slug}`;
const cached = await redis.get(key);
if (cached) return JSON.parse(cached);
const post = await prisma.post.findUnique({ where: { slug } });
if (post) await redis.setex(key, 60, JSON.stringify(post));
return post;
}
- Use revalidate = 60 for ISR-style freshness where appropriate.
Day 8–9: Auth migration
- Legacy PHP session → JWT session bridge:
- Create a compat endpoint on PHP that exchanges legacy PHPSESSID for a short-lived JWT.
- Next.js middleware verifies JWT for protected routes.
// app/api/auth/session/route.ts
import { NextResponse } from "next/server";
export async function GET(req: Request) {
// call legacy to exchange cookie -> jwt
// set httpOnly "session" cookie for Next
return NextResponse.json({ ok: true }, { headers: { "Set-Cookie": `session=JWT_HERE; HttpOnly; Path=/; Secure; SameSite=Lax` }});
}
Day 10: Forms & mutations
- Replace PHP form posts with Next.js Server Actions or API routes:
// app/contact/actions.ts
"use server";
import { prisma } from "@/lib/prisma";
export async function submitContact(formData: FormData) {
await prisma.contact.create({ data: { name: formData.get("name") as string, email: formData.get("email") as string }});
}
Day 11: Media & assets
- Migrate /uploads to S3 + CloudFront.
- Write a script to copy and rewrite URLs in content:
node scripts/migrate-uploads.js # copies to S3 and updates DB references
Day 12–13: Critical flows
- Rebuild homepage, top landing pages, product/blog detail, and search.
- Snapshot test legacy vs new HTML where SEO matters.
- Add Playwright E2E for top 5 flows.
Deliverables end of Week 2:
Key pages & flows live on Next.js behind the same domain, auth bridged, forms functional, media served via CDN, tests passing.
Week 3 — Perf, SEO, Rollout & Cutover
Day 14–15: Performance
- Audit with Lighthouse and Web Vitals.
- Use next/image (remotePatterns) and proper sizes.
- Add HTTP caching for static/edge responses.
- Preload critical fonts; remove render-blocking assets.
Day 16: SEO & redirects
- Maintain 1:1 URL parity; add 301 for any changes:
// next.config.js
module.exports = {
async redirects() {
return [
{ source: "/old.php?id=:id", destination: "/products/:id", permanent: true },
];
},
};
- Add sitemap + robots via app routes:
/app/sitemap.ts
/app/robots.txt/route.ts
Day 17: Observability
- Sentry for errors, Uptime for monitoring, structured JSON logs.
- Add request-id headers in Nginx and propagate to logs.
Day 18–19: Staged rollout
- Blue-green: stand up Next.js as blue, keep PHP as green.
- Shift 10% traffic to blue via Nginx map or ALB weighted target groups.
- Watch errors/metrics, then 50%, then 100%.
Day 20–21: Decommission & cleanup
- Remove unused PHP routes; keep a /legacy admin-only path for a week.
- Final content resync; lock writes on legacy.
- Hand off docs & runbook.
Deliverables end of Week 3:
Next.js fully serves the site, SEO intact, improved performance, monitoring live; legacy safely retired.
Key Implementation Details
1) Data Access with Prisma (keeping legacy schema)
// lib/prisma.ts
import { PrismaClient } from "@prisma/client";
export const prisma = new PrismaClient();
- Use db pull to respect existing tables.
- Avoid destructive migrations early; add new tables in a shadow schema if needed.
2) Re-using PHP logic safely
If an edge case is encoded in PHP, wrap it behind a small internal endpoint and call it from Next.js initially. Replace with TypeScript later.
3) Caching strategy
- Edge or route-level cache for read-heavy pages.
- Redis for DB results and expensive aggregations (TTL 60–300s).
- Invalidate keys on writes (Prisma middleware or service layer).
4) Accessibility & UX
- Server components → minimal JS.
- Accessible forms, focus management, and skeleton/streaming for perceived speed.
Testing Matrix
- Unit: helpers, services (Vitest/Jest).
- Integration: API routes & Server Actions with test DB.
- E2E: Playwright for top paths & form submissions.
- Contract tests: ensure JSON shapes match any external consumers.
Deployment Options
- Vercel: simplest for Next.js; connect to existing DB/Redis; keep Nginx (or middleware) for legacy routing.
- EC2 + Nginx + PM2: control and proximity to legacy infra.
- Docker: reproducible builds; push to ECR; run via ASG.
Example GitHub Action (Vercel + Prisma deploy):
name: Deploy Web
on: [push]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run build
- run: npx prisma generate
- uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
working-directory: apps/web
Risks & How I Mitigated Them
- SEO loss → URL parity, canonical tags, 301s, sitemap parity.
- Auth mismatch → JWT bridge; dual-write sessions until cutover.
- Hidden business rules in PHP → temporary service wrapper; replace later.
- Timeline → prioritize top 20% of traffic first; cut scope that doesn’t move KPIs.
Results (typical outcomes)
- TTFB down 30–50% on content pages
- LCP improved via server components + optimized images
- Deploy times from hours → minutes via CI/CD
- Dev velocity up thanks to TypeScript, component reuse, and testing
(These improvements are representative of similar migrations; exact numbers vary by project.)
Migration Checklist (copy/paste)
- URL inventory & priority map
- Prisma introspection; Redis set up
- Nginx or middleware proxy for strangler pattern
- App Router routes & metadata parity
- Auth bridge (PHP session → JWT)
- Top pages migrated; forms via Server Actions
- Assets to S3 + CDN; rewrite URLs
- Web Vitals targets met; tests passing
- Staged rollout (10% → 50% → 100%), monitors green
- Legacy decommission plan