The mega prompt

Vite/React to Next.js.

Mega Prompt: Vite/React to Next.js Conversion for SEO

Migrate a Vite/React (client-rendered SPA) project to a Next.js 14 app (Pages Router, TypeScript). Goal: identical design and functionality, fully server-rendered for SEO, with no missing or rewritten styles.

0. Inventory (do this first, before writing any code)

List every route from the react-router-dom config and its target file/page.
List every component in /src/components/ and every page-level component.
List every data source per route: static content, fetch/axios calls, context providers, or global state (Redux/Zustand/etc.) that a page depends on for its primary content.
List every stylesheet: global CSS, CSS Modules, Tailwind config, and any CSS-in-JS.
List all environment variables (import.meta.env.*) and where they're used.
List all static assets referenced from /public or imported directly into components.
Output this inventory as a checklist. You will check items off as they're migrated and use it for final verification.

1. CSS Migration Policy (critical — do not skip)

Port ALL existing styles verbatim first: global stylesheets and CSS Modules as-is. Do not rewrite, summarize, or convert to Tailwind during this pass.
Every selector, media query, keyframe, and vendor prefix in the source must have a matching rule in the output — verify before omitting anything as "unused."
Only after verbatim migration is complete and verified, optionally refactor incrementally to Tailwind utility classes, one component at a time — never as a blanket rewrite.

2. Project Setup

Next.js 14, Pages Router, TypeScript, Tailwind CSS configured but not yet applied (see section 1).
Move import.meta.env.VAR usage to process.env.NEXT_PUBLIC_VAR (client-exposed) or process.env.VAR (server-only), and set up next.config.js / .env.local accordingly.

3. Component Migration

Transfer all reusable components from /src/components/ to /components/, unchanged, other than import path updates.
Flag any component that reads window, document, or browser-only APIs at render time — these need useEffect or dynamic(..., { ssr: false }) once moved (see section 5).

4. Page Conversion & Server Rendering

For each route, create a matching file in /pages/.
Use getStaticProps for static marketing/content pages (SSG).
Use getServerSideProps for pages whose primary content depends on request-time or frequently-changing data (SSR).
Move any data fetching that currently happens client-side (in useEffect on mount) into getStaticProps/getServerSideProps if it affects primary, crawlable content. Client-side fetching is only acceptable for content that is genuinely user-specific or post-interaction (e.g. a dashboard after login).
Confirm all primary content is present in "View Source" without JavaScript running.

5. Routing & Links

Replace react-router-dom's <Link>/<NavLink> with next/link, and useNavigate/useHistory with useRouter from next/router.
Replace useParams with the page's file-based route params (from getStaticProps/getServerSideProps context or useRouter().query).
Preserve the existing URL structure exactly (e.g. /industry/sub-industry).
Remove the SPA entry point (main.tsx, index.html, <BrowserRouter>) — these have no equivalent in the Pages Router.

6. Technical SEO

<Head> on every page with <title> and <meta name="description"> populated from the page's actual content (not hardcoded placeholders).
Exactly one <h1> per page, semantic landmarks, descriptive link text.
Confirm all content is accessible without JavaScript, not just visually present after hydration.

7. Functionality & Styling

Preserve all interactivity post-hydration: forms, modals, event handlers, animations.
Confirm Tailwind and CSS Modules apply identically to the original.
Confirm any global state/context providers still wrap the app correctly via _app.tsx.

8. Output & Verification

Deliver the complete converted project and a clear folder-structure tree view.

Before delivery:

Screenshot each original Vite page and its Next.js equivalent at the same viewport width; confirm they match visually. Fix any discrepancy before proceeding.
Confirm every selector in the inventory (step 0) has a corresponding rule present in the shipped output.
curl the built homepage and confirm all key content is present in raw HTML.
Manually verify interactive elements still work after the page loads.
Run Lighthouse; report SEO and performance scores.

Important Note

This mega prompt is highly effective, but it's not foolproof. It works correctly about 99% of the time, but there can be exceptions based on your project's specific configuration.

Always back up your code! Before running a large-scale migration like this, make sure you have a complete backup of your project or know how to revert the changes using version control like Git (e.g., `git reset --hard` or `git checkout .`).

How to use this mega prompt.

This prompt is designed to be used with a variety of AI-powered coding assistants and tools. The goal is to provide the AI with a comprehensive set of instructions to perform the migration accurately.

Supported Tools

You can use this prompt with a wide range of AI coding assistants, including:

Google's AI tools like Jules
OpenAI's Codex and its integrations
Modern IDEs with AI capabilities like Visual Studio, Cursor, Trae, etc.

Usage Steps

Copy the Prompt: Click the copy button on the prompt box above to copy the entire text to your clipboard.
Open Your AI Tool: Go to your preferred AI coding assistant or IDE.
Paste and Run: Paste the complete prompt into the chat or command input field of the AI tool. The AI should then begin the process of analyzing your code and suggesting the necessary changes for the migration.
Review and Apply: Carefully review the changes suggested by the AI. Apply them incrementally and test your application at each step to ensure everything is working correctly.

Why migrate from Vite/React to Next.js?

While Vite is an incredibly fast build tool and React is a powerful library for building user interfaces, a pure client-side rendered (CSR) React app has significant SEO limitations. Next.js provides a robust framework that solves these challenges and offers additional benefits for production-ready applications.

Superior SEO with Server-Side Rendering (SSR) & Static Site Generation (SSG)

A standard Vite/React project relies on JavaScript to build the page content in the user's browser. This is a problem for search engine crawlers, which may struggle to properly index all your content. Next.js, on the other hand, pre-renders the HTML on the server, sending a fully-formed page to the browser. This ensures that crawlers see all the content, leading to better indexing and higher search rankings.

Built-in Performance Optimizations

Next.js comes with out-of-the-box features that improve site speed, a critical ranking factor for Google. The framework automatically handles code splitting, image optimization with the <Image> component, and prefetching of links, all of which contribute to faster page loads and a better user experience.

Simplified Routing and API Routes

Next.js uses a file-system based routing system that eliminates the need for manual setup with libraries like react-router-dom. This simplifies development and ensures clean, SEO-friendly URLs. Additionally, Next.js allows you to create API endpoints directly within your project, enabling full-stack capabilities without needing a separate server.

Hybrid Approach for Flexibility

Next.js allows you to choose the best rendering strategy for each page. You can use SSG for static marketing pages (e.g., about, contact) for maximum speed, and SSR for dynamic content (e.g., e-commerce product pages), providing the best of both worlds.

A deeper dive into the migration process.

Project Planning & Strategy 🗺️

Before you write a single line of code, take a step back and perform a detailed audit of your existing Vite/React project. Start by mapping out all your existing routes and their corresponding components. This is a critical step to avoid missing any pages during the migration. Identify which pages are static (like "About Us" or "Contact") and which are dynamic (like a blog post or a product page). This will help you decide whether to use SSG or SSR for each route, a core decision in Next.js. Also, make note of any client-side-only functionality, such as components that rely on browser APIs.

Code Refactoring & Optimization ⚙️

Next.js works best with modern React practices. As you migrate, take the opportunity to refactor any older class components into functional components with hooks. This aligns your project with the current standard and makes the codebase cleaner.

A major change is moving from client-side data fetching to server-side fetching. Convert your useEffect hooks that fetch data from an API into getServerSideProps or getStaticProps. This ensures the data is included in the initial HTML, which is a major win for SEO. For example, instead of an empty div that gets filled with data after a network request, your page will load with all the content already there.

Finally, place all your static assets like images, fonts, and CSS files in the new Next.js /public directory. Update all your paths to be root-relative. For instance, an image at src/assets/logo.png will now be at /logo.png.

Post-Migration & Deployment 🚀

Once the code is converted, testing is crucial. Verify that your pages render correctly on the server by using a tool like curl or by viewing the page source. Look for a fully-formed HTML document, not just an empty root div. Check for any hydration errors in the browser console, which can happen if server-rendered content doesn't match the client-side version.

For deployment, the process is straightforward thanks to platforms like Vercel and Netlify. Both automatically detect a Next.js project and handle all the necessary configurations. You simply connect your Git repository, and the platform will build, optimize, and deploy your site, giving you a smooth transition to a production environment.