The mega prompt

HTML to Next.js.

Mega Prompt: HTML to Next.js Conversion for SEO

Migrate a pure HTML website to a Next.js 14 app (Pages Router, TypeScript). Goal: identical visual output and functionality to the original, fully server-rendered for SEO, with no missing or rewritten CSS.

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

List every HTML file and its corresponding URL path.
List every CSS file, <style> block, and inline style="" attribute across the site.
List every asset referenced (images, fonts, icons, JS).
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 CSS verbatim into the new project first, as plain .css files (global stylesheet or CSS Modules). Do not rewrite, summarize, "clean up," or convert it to Tailwind during this pass.
Every selector, media query, keyframe, and vendor prefix in the source must have a matching rule in the output. Do not omit rules that look redundant or unused — verify before removing anything.
If a stylesheet is large, migrate it in full; do not truncate or paraphrase it.
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.
Preserve the CSS load order (specificity/cascade matters — reordering will change rendering).

2. Project Bootstrap

Next.js 14, Pages Router, TypeScript.
Global stylesheet imported in _app.tsx containing the verbatim ported CSS.

3. Routing & Assets

Map each HTML file to a matching file under /pages, preserving the exact URL structure (including trailing slashes/index conventions if the original used them).
Move all static assets to /public, preserving relative paths where practical, and update every reference.

4. Rendering Policy

Every indexable page must use getStaticProps or getServerSideProps — content must be present in the initial HTML response.
No useEffect or client-side fetching for primary/indexable content.
Use getStaticPaths for templated collections (blog posts, docs, etc.).

5. Layouts & Components

Extract shared header/nav/footer into a Layout component.
Convert repeated HTML blocks into reusable components, but do not alter their markup or class names while doing so — structural refactors and visual changes are separate steps.

6. Technical SEO

Centralized SEO component/utility for metadata.
Per-page <title>, meta description, canonical URL, Open Graph tags.
Exactly one <h1> per page, semantic landmarks (<header>, <nav>, <main>, <footer>), descriptive link text.

7. Performance

Replace <img> with next/image, preserving original width/height/aspect ratio.
Preload critical fonts; lazy-load below-the-fold, non-critical assets.

8. Deployment

Provide netlify.toml using the official Next.js runtime (SSR-compatible, not static export).
Note the GitHub-sync one-click deploy flow.

9. Verification (required before delivery)

For every migrated page:

Screenshot the original HTML file and the new Next.js page at the same viewport width; confirm they match visually. Flag and fix any discrepancy — do not proceed with unresolved visual diffs.
Confirm every selector in the inventory (step 0) has a corresponding rule present in the shipped output.
curl the built page and confirm full content is present in raw HTML (not just an empty root div).
Run Lighthouse; report SEO and performance scores.

Deliver the complete project only after this verification step passes.

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 pure HTML to Next.js?

While a pure HTML website is as "crawlable" as it gets, it lacks the modern tools and optimizations that are essential for competing in today's digital landscape. Migrating to Next.js provides a significant boost in both development efficiency and SEO performance.

Automated SEO & Performance

A pure HTML site requires manual effort for every SEO detail. Next.js automates this process by providing features like automatic code splitting, optimized image loading with <Image>, and easy metadata management with the <Head> component. These built-in tools help you achieve better Core Web Vitals scores and reduce manual labor.

Centralized & Reusable Components

A pure HTML site is often a collection of repeated code snippets. Next.js allows you to break your site into reusable components (e.g., a header, a footer, a navigation bar). This not only makes your codebase cleaner and easier to maintain but also ensures consistency across your site.

Dynamic Content Management

Pure HTML is great for static content but becomes a nightmare to manage when content needs to be updated or personalized. Next.js, with its ability to fetch data on the server with getStaticProps or getServerSideProps, allows you to connect to a headless CMS or API to manage your content dynamically, without sacrificing SEO.

Modern Development Workflow

Next.js provides a superior developer experience with features like file-based routing and live reloading, which drastically speed up the development and iteration process. You can build and deploy a site in a fraction of the time it would take with a traditional HTML workflow.

A deeper dive into the migration process.

The "Why" Behind the Change 🤔

A pure HTML site is like a collection of static files. Every time you want to make a small change, you have to find and manually edit every file where that element appears. Next.js, with its component-based architecture, changes this. You can create a reusable Header component and use it on every page. Any future change to the header only needs to be made in one place. This significantly improves the developer experience (DX) and makes your project far more scalable and maintainable.

Technical Deep Dive 💻

To start, think of your HTML site in terms of components. Take your header.html and turn it into a Header.tsx component. Then, create a Layout.tsx component that wraps your header, footer, and a main content area using props.children. Your individual pages can then simply import and use this shared layout.

For technical SEO, Next.js gives you a massive advantage. You can create a centralized SEO component that automatically generates metadata for each page. This ensures every page has a unique title, meta description, and canonical URL. You can also implement JSON-LD for rich snippets, which helps Google understand your site's content better. Next.js handles this seamlessly, allowing you to focus on your content instead of manual SEO tags.

The Deployment Process 🌐

The deployment of a Next.js app is a far cry from simply uploading a folder of HTML files via FTP. Platforms like Vercel and Netlify have made this process incredibly efficient. They are built to work with Next.js and automate key steps like server-side rendering and static asset caching.

For a Netlify deployment, you simply add a netlify.toml file to your project. This file specifies your build command and the output directory. Most importantly, it enables the Next.js runtime, which is what allows Netlify to handle your server-rendered pages correctly. A simple push to GitHub, and your site is live, optimized, and ready for crawlers.