Upgrade workflow for Astro 6 for Agents

Astro 7 was released this week.
So I thought I share my workflow file for updating Astro 5 to Astro 6.
There were some breaking changes that needed to be addressed and took me some time.
So it may be useful for anyone upgrading.

The upgrade workflow was originally made for Windsurf Editor (now Devin) but will probably work in other agents too.

The Upgrade from Astro 6 to Astro 7 went pretty smooth with just npx @astrojs/upgrade.
My project was not affected by any of the rather small breaking changes for this release.

By the way, Astro now also recommends to pass its upgrade guide into your agent.

Using a coding agent?
Copy this prompt to upgrade your project.
Upgrade my Astro project to v7. Follow the migration guide at
https://docs.astro.build/en/guides/upgrade-to/v7/

So here is my workflow for upgrading Astro 5 to Astro 6.
Paste into your agent or add it as context file if your Agent does not support workflows.

---
description: Upgrade an Astro project to version 6.x
---

# Upgrade to Astro 6 Workflow

This workflow guides you through upgrading an Astro project from v5.x to v6.x.

## Prerequisites

- Node.js 22+ (Astro 6 requires Node 22 or later)
- Existing Astro 5.x project

## Step 1: Upgrade Dependencies

Update Astro and official integrations to v6:

```bash
npx @astrojs/upgrade
```

Or manually update package.json:
- `astro`: `^6.x.x`
- `@astrojs/mdx`: `^5.x.x` (or latest compatible)
- Other `@astrojs/*` integrations to their latest major versions

Then run:
```bash
npm install
```

## Step 2: Check for Legacy Content Collections Flag

If your `astro.config.mjs` has the legacy flag, remove it:

```diff
export default defineConfig({
-  legacy: {
-    collections: true,
-  },
});
```

## Step 3: Add Loaders to Content Collections

Astro 6 requires explicit loaders for all content collections. Update `src/content.config.ts`:

### For file-based collections (JSON, etc.):
```typescript
import { file } from 'astro/loaders';

const gallery = defineCollection({
  loader: file("src/content/gallery.json"),
  schema: ...
});
```

### For glob-based collections (Markdown, MDX):
```typescript
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: "./src/content/blog" }),
  schema: ...
});
```

### Common loader imports:
```typescript
import { file, glob } from 'astro/loaders';
```

## Step 4: Update Render API

The `entry.render()` method is replaced with a standalone `render()` function.

### In page files using `getCollection()`:

```diff
-import { getCollection } from 'astro:content';
+import { getCollection, render } from 'astro:content';

// For single entry rendering:
-const { Content } = await entry.render();
+const { Content } = await render(entry);

// For array mapping:
{
  entries.map(async (entry) => {
-   const { Content } = await entry.render();
+   const { Content } = await render(entry);
    return <Content />;
  })
}
```

## Step 5: Update Deprecated Zod Imports (Optional)

While still working (deprecated), consider updating Zod imports for future compatibility:

```diff
-import { defineCollection, z } from 'astro:content';
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
```

## Step 6: Build and Verify

Run the build to check for errors:

```bash
npm run build
```

### Common errors and fixes:

**`entry.render is not a function`**
- You missed updating `entry.render()` to `render(entry)`
- Check all files that use `getCollection()`

**`ContentCollectionMissingALoaderError`**
- A collection is missing the `loader` property
- Add appropriate `file()` or `glob()` loader

**`LegacyContentConfigError`**
- You're using `src/content/config.ts` instead of `src/content.config.ts`
- Rename the file to the new location

## Step 7: Test Development Server

```bash
npm run dev
```

Verify all pages load correctly, especially:
- Content collection pages (blog, news, etc.)
- Pages using rendered MDX content
- Image optimization with `astro:assets`

## Post-Upgrade Checklist

- [ ] All content collections have explicit loaders
- [ ] All `entry.render()` calls updated to `render(entry)`
- [ ] No `legacy.collections` flag in config
- [ ] Build completes without errors
- [ ] All pages render correctly in dev
- [ ] Production build tested

## References

- [Official Astro 6 Upgrade Guide](https://docs.astro.build/en/guides/upgrade-to/v6/)
- [Content Layer API Documentation](https://docs.astro.build/en/guides/content-collections/)Code language: PHP (php)

Here it is also as Gist: astro6-upgrade-workflow.md