Awesome-omni-skill migrate

Guide migration to Astro from other frameworks or between Astro versions. Use when converting Next.js, Nuxt, Gatsby projects or upgrading Astro.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/migrate" ~/.claude/skills/diegosouzapw-awesome-omni-skill-migrate-9b74ba && rm -rf "$T"

manifest: skills/development/migrate/SKILL.md

source content

Migrate to Astro

When to Use

Migrating from Next.js, Nuxt, Gatsby, or other frameworks
Upgrading between major Astro versions
Converting a static HTML site to Astro
Moving from Create React App to Astro

Instructions

1. Identify Migration Path

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 v3 → v4	Low	Minor breaking changes
Astro v4 → v5	Low-Medium	Content layer changes

2. Project Setup

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"
  }
}

3. Migration Patterns

Static HTML → Astro

Rename
```
.html
```
to
```
.astro
```
Move to
```
src/pages/
```
Extract repeated sections to
```
src/layouts/
```
Convert to components as needed

---
// 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>

Next.js → Astro

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 } from 'astro:content'

export async function getStaticPaths() {
  const posts = await getCollection('blog')
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }))
}

const { post } = Astro.props
const { Content } = await post.render()
---

<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 />

Nuxt → Astro

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

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 Zod schema

import { defineCollection, z } from 'astro:content'

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    // Match your Gatsby frontmatter fields
  }),
})

export const collections = { blog }

4. Astro Version Upgrades

Upgrade command:

npx @astrojs/upgrade

v4 → v5 Key Changes:

Content collections now use "Content Layer" API
```
astro:content
```
imports updated
Some deprecated features removed

Check migration guide: docs.astro.build/guides/upgrade-to/v5

5. Common Migration Tasks

Move static assets

public/images/ → public/images/  (same)
src/assets/   → src/assets/      (processed by Vite)

Update image imports

---
import { Image } from 'astro:assets'
import heroImage from '../assets/hero.jpg'
---

<Image src={heroImage} alt="Hero" width={800} height={400} />

Convert CSS

Global CSS → Import in layout
CSS Modules → Work as-is
Styled Components → Use with React integration
Tailwind →
```
npx astro add tailwind
```

Environment variables

// Next.js
NEXT_PUBLIC_API_URL

// Astro
PUBLIC_API_URL  // Client-side
API_SECRET      // Server-side only