The mega prompt

Astro to Next.js.

Mega Prompt: Astro to Next.js Migration for SEO

Migrate an Astro.js project to a Next.js 14 app (Pages Router, TypeScript). Goal: full feature parity and identical rendered output to the original, fully server-rendered for SEO, with no missing or rewritten styles.

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

List every file under /src/pages, its route, and its rendering mode (static, SSR, or hybrid via Astro's export const prerender).
List every component/layout and where it's used, including any using Astro slots.
List every stylesheet: global CSS/SCSS, Tailwind config, and all component-scoped <style> blocks.
List every .md/.mdx content file and any content collections config.
List every static asset in /public.
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 as-is, and each component's scoped <style> block as a matching CSS Module (Component.module.css) or global class if it was previously global. 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."
Preserve Astro's scoping behavior: styles scoped to one component must not leak into others in the new project.
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. Bootstrap

Next.js 14, Pages Router, TypeScript, Tailwind CSS configured but not yet applied (see section 1).

3. Page & Routing

Map each .astro file under /src/pages to a corresponding file under /pages, preserving the exact URL structure.
Convert dynamic routes to [param].tsx with getStaticPaths, and catch-all routes to [...slug].tsx.
Confirm final URLs are unchanged and clean.

4. Components & Layouts

Convert Astro components and layouts into React components without altering their markup or class names — structural conversion and visual changes are separate steps.
Replace Astro slots with props.children (named slots become named props).

5. Rendering Policy

All primary content must be server-rendered by default via getStaticProps or getServerSideProps — content must be present in the initial HTML response.
No client-side fetching for primary/indexable content.
Use dynamic(..., { ssr: false }) only for genuinely browser-only components (e.g. those touching window directly), and only after confirming they don't hold indexable content.

6. Data & Content Migration

Move all assets from /public to the Next.js /public directory, preserving paths.
Replace <img> with next/image, preserving original width/height/aspect ratio.
If the project uses .md/.mdx or Astro content collections, integrate next-mdx-remote or Contentlayer and migrate the content files and their frontmatter schema as-is.

7. Technical SEO

<Head> on every page with <title>, meta description, canonical URL, and Open Graph tags.
Exactly one <h1> per page, semantic landmarks, descriptive link text.

8. Output & Verification

Deliver a complete project scaffold: one converted static page, one dynamic page, a shared layout, and an API route. Include a README with run/build instructions.

Before delivery:

Screenshot each original Astro 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, correctly scoped.
curl the built pages and confirm full content is present in raw HTML.
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 Astro to Next.js?

Astro is a performance-focused static site builder known for its "zero JavaScript by default" approach. While it excels at content-heavy websites, Next.js offers a more versatile platform, especially for applications that require a mix of static and dynamic content.

Full-Stack Capabilities

Astro is primarily a front-end build tool. While it can be extended with server-side integrations, Next.js has a robust, built-in system for creating API routes and running server-side logic (e.g., database queries, authentication). This makes it a better choice for building complex, full-featured web applications.

Built-in React Ecosystem

Next.js is a React framework, which means it fully integrates with the vast and mature React ecosystem. For a developer or team already familiar with React, the transition is seamless, and you can leverage all your existing knowledge and a rich library of components.

Incremental Static Regeneration (ISR)

While Astro and Next.js both support SSG, Next.js offers ISR. This powerful feature allows you to update static pages after the initial build without requiring a full site rebuild. This is a game-changer for sites with large amounts of content (e.g., news sites, blogs) that need to stay fresh while maintaining the performance benefits of a static site.

First-Class Hybrid Rendering

Next.js was designed from the ground up to handle both static and server-rendered pages seamlessly. This hybrid approach is a core feature, whereas in Astro, server-side rendering is more of an opt-in integration that may not be as deeply integrated.

A deeper dive into the migration process.

Framework Differences & Philosophy 🧠

At its core, Astro's "zero JavaScript by default" approach is designed for static content sites where performance is paramount. Next.js, in contrast, is a hybrid framework that blends SSG for static content with SSR for dynamic pages. This makes it ideal for a wider range of applications, especially those that need user authentication, data fetching, or a more integrated backend. Next.js’s full-page hydration model also differs from Astro’s component islands; instead of only hydrating the interactive parts of a page, Next.js hydrates the entire document, which can simplify some complex state management tasks.

Content & Data Management 📑

If your Astro site uses Markdown (.md or .mdx) files for content, you'll need a new pipeline in Next.js. A common approach is to use a combination of fs (file system) and a library like gray-matter to read and parse your Markdown files. You can then use getStaticProps to pass the content as props to your React components, ensuring all your content is pre-rendered.

For a more scalable approach, you might want to integrate a headless CMS like Contentful or Sanity. Next.js's built-in data fetching makes this seamless. For a blog, you can use getStaticProps with getStaticPaths to fetch all your articles from the CMS at build time, ensuring fast, static pages while keeping your content management separate and easy to update.

Advanced Features & Ecosystem 🛠️

Next.js offers powerful features beyond static site generation. Incremental Static Regeneration (ISR) is a standout feature that allows you to update static pages without having to rebuild your entire site. This is perfect for large content sites where you want the performance of a static build but the freshness of dynamic content. You can also leverage Next.js’s middleware for authentication, redirects, or A/B testing at the Edge. This kind of server-side functionality is deeply integrated into Next.js, making it a more comprehensive solution than Astro.