Menu
Guide migration to Astro from other frameworks or between Astro versions. Use when converting Next.js, Nuxt, Gatsby projects or upgrading Astro.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Guide complete integration setup including post-install configuration. Use when adding UI frameworks, adapters, or tooling to an Astro project.
Set up and configure Astro content collections with the current Content Layer API and type-safe schemas. Use when creating blogs, docs, or any structured content.
Search and retrieve Astro documentation using the Astro Docs MCP. Use when answering questions about Astro APIs, configuration, integrations, or best practices.
Scaffold Astro components, pages, and layouts with best practices. Use when creating new .astro files or converting designs to components.
| name | migrate |
| description | Guide migration to Astro from other frameworks or between Astro versions. Use when converting Next.js, Nuxt, Gatsby projects or upgrading Astro. |
| From | Complexity | Key Changes |
|---|---|---|
| Static HTML | Low | Wrap in .astro, add layouts |
| Next.js (Pages) | Medium | Route structure similar, convert JSX |
| Next.js (App) | Medium-High | Server components map well to Astro |
| Nuxt | Medium | Vue components work with integration |
| Gatsby | Medium | GraphQL → Content Collections |
| Create React App | Medium | Add routing, convert to islands |
| Astro v4 → v5 | Low-Medium | Content Layer changes begin |
| Astro v5 → v6 | Medium | Content collections, Astro.glob(), and runtime changes |
Create new Astro project alongside existing:
npm create astro@latest my-astro-site
Or convert in-place by installing Astro:
npm install astro
Update package.json scripts:
{
"scripts": {
"dev": "astro dev",
"build": "astro build",
"preview": "astro preview"
}
}
If upgrading to Astro 6, verify the runtime first:
node --version
Astro 6 requires Node 22.12.0 or newer. Also upgrade official integrations and adapters alongside Astro to avoid version skew.
.html to .astrosrc/pages/src/layouts/---
// src/layouts/Layout.astro
const { title } = Astro.props
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>{title}</title>
</head>
<body>
<slot />
</body>
</html>
Pages Router:
| Next.js | Astro |
|---|---|
pages/index.js | src/pages/index.astro |
pages/blog/[slug].js | src/pages/blog/[slug].astro |
getStaticProps | Frontmatter code block |
getStaticPaths | getStaticPaths() export |
_app.js | src/layouts/Layout.astro |
next/image | astro:assets Image component |
next/link | Standard <a> tags |
Convert a Next.js page:
// Next.js: pages/blog/[slug].js
export async function getStaticPaths() {
const posts = await getPosts()
return { paths: posts.map(p => ({ params: { slug: p.slug } })) }
}
export async function getStaticProps({ params }) {
const post = await getPost(params.slug)
return { props: { post } }
}
export default function Post({ post }) {
return <article><h1>{post.title}</h1></article>
}
---
// Astro: src/pages/blog/[slug].astro
import { getCollection, render } from 'astro:content'
export async function getStaticPaths() {
const posts = await getCollection('blog')
return posts.map(post => ({
params: { slug: post.id },
props: { post },
}))
}
const { post } = Astro.props
const { Content } = await render(post)
---
<article>
<h1>{post.data.title}</h1>
<Content />
</article>
Keep React components:
npx astro add react
Then use with client directives:
---
import InteractiveWidget from '../components/InteractiveWidget.tsx'
---
<InteractiveWidget client:visible />
npx astro add vue
| Nuxt | Astro |
|---|---|
pages/ | src/pages/ (similar) |
components/ | src/components/ |
layouts/ | src/layouts/ |
nuxt.config.ts | astro.config.mjs |
| Auto-imports | Explicit imports |
Vue components work directly:
---
import MyVueComponent from '../components/MyVueComponent.vue'
---
<MyVueComponent client:load />
| Gatsby | Astro |
|---|---|
| GraphQL queries | Content Collections |
gatsby-image | astro:assets Image |
gatsby-plugin-* | Astro integrations |
| MDX pages | MDX in content collections |
Convert GraphQL to Content Collections:
// Gatsby: gatsby-node.js with GraphQL
// → Astro: src/content.config.ts with a loader and schema
import { defineCollection } from 'astro:content'
import { glob } from 'astro/loaders'
import { z } from 'astro/zod'
const blog = defineCollection({
loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
schema: z.object({
title: z.string(),
date: z.coerce.date(),
// Match your Gatsby frontmatter fields
}),
})
export const collections = { blog }
Upgrade command:
npx @astrojs/upgrade
v5 → v6 Key Changes:
src/content/config.ts moves to src/content.config.tsloaderz should come from astro/zodentry.id replaces legacy slug usage in collection routingentry.render() becomes render(entry)Astro.glob() is removed in favor of import.meta.glob() or getCollection()<ViewTransitions /> is removed; use <ClientRouter />Astro.site inside getStaticPaths() should become import.meta.env.SITEAstro 6 upgrade checklist:
src/content/config.ts to src/content.config.tsloader to every collectionimport { defineCollection, z } from 'astro:content' with import { defineCollection } from 'astro:content' and import { z } from 'astro/zod'post.slug with post.idpost.render() with render(post)Astro.glob() with import.meta.glob() or getCollection()<ViewTransitions /> with <ClientRouter />Check migration guide: docs.astro.build/guides/upgrade-to/v6
public/images/ → public/images/ (same)
src/assets/ → src/assets/ (processed by Vite)
---
import { Image } from 'astro:assets'
import heroImage from '../assets/hero.jpg'
---
<Image src={heroImage} alt="Hero" width={800} height={400} />
npx astro add tailwind// Next.js
NEXT_PUBLIC_API_URL
// Astro
PUBLIC_API_URL // Client-side
API_SECRET // Server-side only
---
// Before
const posts = await Astro.glob('./posts/*.md')
// After
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }))
---
For content collections, prefer getCollection() instead of raw globs.