Kampmax
Career7 min read

I'm just trying something different

edgfaerfb zcvresbdfdsf sd dfdf

Odunayo Alade
Updated October 5, 2026
I'm just trying something different

Hello here

Hello here

great

Next.js → React + Vite Migration

Act as a:

  • Senior React Engineer

  • Senior Frontend Architect

  • Senior UI/UX Engineer

  • Senior Full-Stack Engineer

  • Senior QA/Test Engineer

  • Senior Migration Engineer

Your task is to migrate this existing Next.js frontend application to React + Vite + TypeScript.

PRIMARY OBJECTIVE

Convert the existing frontend from:

  • Next.js

  • Next.js App Router

  • TypeScript

  • Tailwind CSS

  • existing component system

  • existing API integration

  • existing authentication

  • existing state/data-fetching logic

to:

  • React

  • Vite

  • TypeScript

  • Tailwind CSS

  • React Router

  • the existing UI/component libraries where compatible

  • the existing API/backend

  • the existing authentication architecture where compatible

The final application must be deployable as a static React application on standard cPanel/Apache hosting without Node.js running on the production server.

CRITICAL RULE

DO NOT rewrite, modify, migrate, or replace the backend unless absolutely required for frontend compatibility.

The existing Laravel/NestJS API is the source of truth.

Preserve:

  • API endpoints

  • request methods

  • request payloads

  • response structures

  • authentication behavior

  • authorization behavior

  • validation behavior

  • business rules

  • database behavior

  • user roles

  • permissions

  • error handling

  • pagination

  • filtering

  • sorting

  • search

  • file uploads

  • downloads

The migration concerns the FRONTEND.


PHASE 1 — AUDIT BEFORE CHANGING ANYTHING

First inspect the entire existing project.

Do NOT immediately start converting files.

Identify:

Framework

  • Next.js version

  • React version

  • TypeScript version

  • Tailwind version

  • package manager

  • build system

  • UI libraries

  • icon libraries

  • animation libraries

  • form libraries

  • validation libraries

  • state management

  • TanStack Query usage

  • authentication implementation

  • API client implementation

Next.js-specific functionality

Find every use of:

  • next/link

  • next/image

  • next/navigation

  • next/router

  • next/headers

  • next/cookies

  • next/server

  • next/font

  • Server Components

  • Client Components

  • Server Actions

  • Route Handlers

  • middleware

  • Next.js API routes

  • dynamic routes

  • loading.tsx

  • error.tsx

  • not-found.tsx

  • layout.tsx

  • page.tsx

  • metadata

  • redirects

  • rewrites

  • generateMetadata

  • generateStaticParams

  • useSearchParams

  • useParams

  • usePathname

Also identify:

  • server-side data fetching

  • server-only modules

  • environment variables

  • image optimization

  • dynamic imports

  • cookies

  • authentication redirects

  • protected routes

Create a migration report before implementation.


PHASE 2 — DEFINE THE TARGET ARCHITECTURE

Design a clean React + Vite architecture.

Preferred structure:

src/
├── app/
├── assets/
├── components/
├── config/
├── features/
├── hooks/
├── layouts/
├── lib/
├── pages/
├── routes/
├── services/
├── types/
├── utils/
└── main.tsx

Adapt this structure to the existing project where appropriate.

Do not reorganize files unnecessarily.

Prioritize maintainability over excessive abstraction.


PHASE 3 — VITE SETUP

Replace the Next.js runtime with Vite.

Create/configure:

  • vite.config.ts

  • index.html

  • src/main.tsx

Update:

package.json
tsconfig files
environment configuration
build scripts
development scripts
production scripts

The final commands should work:

npm install
npm run dev
npm run build
npm run preview

Production build must generate:

dist/

which can be uploaded to cPanel.


PHASE 4 — ROUTING MIGRATION

Replace Next.js App Router with:

react-router-dom

Preserve all existing routes.

For example:

/app/dashboard
/app/students
/app/students/[id]

should become appropriate React Router routes such as:

/dashboard
/students
/students/:id

Preserve:

  • nested routes

  • dynamic routes

  • protected routes

  • role-based routes

  • redirects

  • query parameters

  • URL state

Create a proper route configuration.

Do NOT scatter routing logic throughout random components.


PHASE 5 — NEXT.JS COMPONENT MIGRATION

Replace Next.js-specific components carefully.

Replace:

import Link from "next/link";

with:

import { Link } from "react-router-dom";

Replace Next.js navigation APIs with React Router equivalents.

Replace:

next/image

with normal image handling or an appropriate existing image component.

Preserve:

  • dimensions

  • responsive behavior

  • loading behavior

  • alt text

  • object-fit behavior

  • accessibility

Do not visually redesign components during migration.


PHASE 6 — AUTHENTICATION

Preserve the existing authentication system.

Do not invent a new authentication architecture.

The migrated application must preserve:

  • login

  • logout

  • token/session handling

  • refresh behavior

  • authentication persistence

  • protected routes

  • role permissions

  • unauthorized handling

  • expired-session handling

If the existing application uses an API token, preserve that flow.

If it uses cookies, carefully determine whether the API requires:

credentials: include

and configure CORS correctly.

Create an appropriate:

AuthProvider
ProtectedRoute
RoleGuard

only where needed.


PHASE 7 — API INTEGRATION

Preserve the existing API client.

If the project uses:

  • Axios

  • Fetch

  • TanStack Query

continue using the existing approach unless there is a strong technical reason to change it.

Environment variables must be migrated from Next.js conventions.

For example:

NEXT_PUBLIC_API_URL

must become:

VITE_API_URL

Update all references accordingly.

Do not hardcode API URLs.

Create an .env.example showing the required variables.


PHASE 8 — TANSTACK QUERY

If the existing project uses TanStack Query, preserve it.

Ensure:

  • QueryClient is configured correctly

  • providers are correctly mounted

  • queries continue working

  • mutations continue working

  • invalidation works

  • pagination works

  • loading states work

  • error states work

  • cache behavior is preserved

Do not replace TanStack Query with unnecessary custom state management.


PHASE 9 — UI PRESERVATION

This is a migration, NOT a redesign.

Preserve the existing:

  • visual hierarchy

  • layout

  • spacing

  • typography

  • colors

  • responsive behavior

  • cards

  • tables

  • forms

  • dialogs

  • dropdowns

  • navigation

  • sidebars

  • dashboards

  • empty states

  • loading states

  • error states

  • mobile layouts

  • accessibility

Do not introduce an "AI-looking" redesign.

Do not add unnecessary animations.

Do not add unnecessary dependencies.

Keep the interface professional, mature, responsive, and production-ready.


PHASE 10 — TAILWIND

Preserve the existing Tailwind implementation where possible.

Do not blindly rewrite all styling.

Ensure Tailwind works correctly with Vite.

Check:

  • content paths

  • global CSS

  • fonts

  • theme configuration

  • dark mode

  • responsive breakpoints

  • custom utilities

  • animations


PHASE 11 — NEXT.JS SERVER FEATURES

For every Next.js server feature, determine whether it is:

  1. unnecessary after migration

  2. replaceable with a client-side React solution

  3. already handled by the existing API

  4. requires a backend change

DO NOT silently remove functionality.

If a Next.js server feature cannot be reproduced in a static React application, document it clearly before changing the implementation.

The backend should be preferred for functionality that requires server-side execution.


PHASE 12 — SEO

Because the application is moving from Next.js to a client-rendered React application, review SEO implications.

For public pages, implement appropriate:

  • document titles

  • meta descriptions

  • canonical URLs where needed

  • Open Graph metadata

  • Twitter/X metadata

  • favicon

  • robots configuration

Use a suitable React-compatible solution where necessary.

Do not pretend client-side rendering provides the same SEO behavior as Next.js SSR.


PHASE 13 — CPANEL / APACHE DEPLOYMENT

The final application must work on standard cPanel hosting without Node.js.

Production workflow:

npm install
npm run build

Then upload:

dist/

to:

public_html/

If React Router is used, provide the required Apache .htaccess configuration so routes such as:

/dashboard
/students
/results

do not return 404 when directly accessed or refreshed.

The .htaccess must safely route application paths to:

index.html

while allowing actual files and assets to load normally.


PHASE 14 — ENVIRONMENT VARIABLES

Convert Next.js public environment variables:

NEXT_PUBLIC_*

to Vite variables:

VITE_*

Example:

NEXT_PUBLIC_API_URL

becomes:

VITE_API_URL

Update every reference.

Create:

.env.example

Do not commit real credentials.


PHASE 15 — TESTING

After migration, perform a complete frontend QA pass.

Test:

Build

npm run build

Routing

Test:

  • homepage

  • authentication pages

  • protected routes

  • dynamic routes

  • nested routes

  • 404 handling

  • browser refresh

Authentication

Test:

  • login

  • logout

  • session persistence

  • expired authentication

  • unauthorized access

  • role restrictions

API

Test:

  • GET

  • POST

  • PUT/PATCH

  • DELETE

  • pagination

  • filtering

  • searching

  • validation errors

  • server errors

  • loading states

UI

Test:

  • desktop

  • tablet

  • mobile

  • forms

  • tables

  • dialogs

  • dropdowns

  • navigation

  • sidebar

  • responsive layouts

Browser

Check:

  • Chrome

  • Edge

  • Firefox where practical

Fix real issues rather than hiding errors.


PHASE 16 — MIGRATION CLEANUP

After confirming the React application works:

Remove obsolete Next.js dependencies and files.

Search the entire project for:

next/
next/link
next/image
next/navigation
next/router
next/server
NEXT_PUBLIC_

There should be no accidental Next.js dependencies remaining unless explicitly documented.

Run:

npm install
npm run build

and confirm there are no build errors.


IMPORTANT ENGINEERING RULES

  1. Do not destroy working functionality.

  2. Do not rewrite the backend.

  3. Do not redesign the application.

  4. Do not change API contracts unnecessarily.

  5. Do not hardcode environment-specific values.

  6. Do not remove features simply because they are inconvenient to migrate.

  7. Do not create duplicate components when existing components can be reused.

  8. Do not install unnecessary packages.

  9. Do not use deprecated React patterns.

  10. Use TypeScript properly.

  11. Maintain accessibility.

  12. Maintain responsive behavior.

  13. Preserve existing business logic.

  14. Preserve existing validation.

  15. Preserve existing error handling.

  16. Preserve existing authentication and authorization.

  17. Prefer simple maintainable solutions.

  18. Do not modify unrelated files.

  19. Do not claim the migration is complete without running the production build.

  20. Do not stop after converting only the obvious pages.


FINAL DELIVERABLE

At completion provide:

1. Migration summary

Explain:

  • what was migrated

  • what was preserved

  • what was replaced

  • what required special handling

2. Next.js dependencies removed

List them.

3. React/Vite dependencies added

List them and explain why each was necessary.

4. Routes migrated

Provide the route mapping.

5. Environment variables

Show the required .env.example.

6. Backend compatibility

Confirm that the existing API contracts remain intact.

7. Testing results

Report:

npm install       PASS/FAIL
npm run build     PASS/FAIL
npm run preview   PASS/FAIL
Routing           PASS/FAIL
Authentication    PASS/FAIL
API integration   PASS/FAIL
Responsive UI     PASS/FAIL

8. cPanel deployment instructions

Give concise instructions for deploying the generated dist/ directory to cPanel.

9. Remaining issues

List only genuine unresolved issues.

Do not claim success if something remains broken.

START

First inspect the existing project and produce the migration/audit findings.

Do not make destructive changes until you understand the current architecture and identify all Next.js-specific functionality.

Share this article

Help fellow students, organizers, and creators find useful insights.

Odunayo Alade

Sharing grounded insights on campus commerce, student enterprise, and practical digital opportunities across higher education communities.

The Campus Ecosystem

Turn Knowledge into Campus Opportunity

Whether you offer freelance services, build a student business, or look for verified campus projects, Kampmax gives you direct visibility.