Upgrade to Astro v6

Astro v6.0 upgrades to Shiki v4.0 for syntax highlighting.

What should I do?

If you are using Shiki-specific APIs, check the Shiki migration guide for their breaking changes and upgrade your project as needed.

Official Astro integrations

All of Astro's official server adapters have also updated to a new major version to accompany the upgrade to Vite v7.0 with Vite's Environment API as the development server and production bundler.

In particular, Astro's Cloudflare adapter has undergone significant changes, and breaking changes to your existing Cloudflare setup are expected.

See the Cloudflare adapter upgrade instructions for detailed migration guidance.

What should I do?

If you are using an Astro adapter for on-demand rendering or other platform-specific features, please check your specific adapter's changelog for upgrade guidance:

• @astrojs/cloudflare CHANGELOG
• @astrojs/netlify CHANGELOG
• @astrojs/node CHANGELOG
• @astrojs/vercel CHANGELOG

Legacy

The following features are now considered legacy features. They should function normally but are no longer recommended and are in maintenance mode. They will see no future improvements and documentation will not be updated. These features will eventually be deprecated, and then removed entirely.

Legacy: content collections backwards compatibility

In Astro 5.x, projects could delay upgrading to the new Content Layer API introduced for content collections because of some existing automatic backwards compatibility that was not previously behind a flag. This meant that it was possible to upgrade from Astro 4 to Astro 5 without updating your content collections, even if you had not enabled the legacy.collections flag. Projects would continue to build, and no errors or warnings would be displayed.

Astro v6.0 removes this automatic legacy content collections support, along with the legacy.collections flag. All content collections must now use the Content Layer API introduced in Astro v5.0 that powers all content collections.

What should I do?

If you experience content collections errors after updating to v6, check your project for any removed legacy features that may need updating to the Content Layer API.

See the Astro v5 upgrade guide for detailed instructions on upgrading legacy collections to the new Content Layer API.

If you are unable to update immediately, you can enable the legacy.collectionsBackwardsCompat flag as a temporary migration helper:

This flag preserves some legacy v4 content collections features:

• Supports the legacy configuration file src/content/config.ts
• Supports type: 'content' and type: 'data' without loaders
• Preserves legacy entry API: entry.slug and entry.render()
• Uses path-based entry IDs instead of slug-based IDs

This is a temporary migration helper. Migrate your collections to the Content Layer API as soon as possible, then disable this flag.

Deprecated

The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.

Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.

Deprecated: Astro in getStaticPaths()

---


  return getPages(Astro.site);
  return getPages(import.meta.env.SITE);
}
---

console.log(isTransitionBeforePreparationEvent(event));
console.log(event.type === 'astro:before-preparation');

console.log(TRANSITION_AFTER_SWAP);
console.log('astro:after-swap');

  const handler = async (req, res) => {
    const response = await app.render(req);
    await NodeApp.writeResponse(response, res);
  };

  return { handler };
}


const app = createApp();


  const response = await app.render(request);
  await writeResponse(response, res);
}

const manifest = await loadManifest(new URL(import.meta.url));
const app1 = new NodeApp(loadManifest);
const app2 = await loadApp(new URL(import.meta.url));

const app = createApp();

// src/content.config.ts



const blog = defineCollection({
  // For content layer you no longer define a `type`
  type: 'content',
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

---

  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---

---

const post = await getEntry('pages', 'homepage');

const { Content, headings } = await post.render();
const { Content, headings } = await render(post);
---
<Content />

<html>
  <head>
    ...
    <ViewTransitions />
    <ClientRouter />
  </head>
</html>

const imageId = '/images/photo.jpg';
const result = await emitESMImage(imageId, false, false);
const result = await emitImageMetadata(imageId);

---
const posts = await Astro.glob('./posts/*.md');
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

{posts.map((post) => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}

  // ...
});

src/pages/test%25file.astro
src/pages/test-file.astro

// Use srcDir, outDir, root, etc. for configuration values

const generated = route.generate(params);

const integration = () => {
    let routes
    return {
        name: 'my-integration',
        hooks: {
            'astro:routes:resolved': (params) => {
                routes = params.routes
            },
            'astro:build:done': ({
                routes
                assets
            }) => {
                for (const route of routes) {
                    const distURL = assets.get(route.pattern)
                    if (distURL) {
                        Object.assign(route, { distURL })
                    }
                }
                console.log(routes)
            }
        }
    }
}

const integration = () => {
    return {
        name: 'my-integration',
        hooks: {
            'astro:build:ssr': (params) => {
                someLogic(params.entryPoints)
            },
        }
    }
}

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

---

---
<html>
  <head>
    <ClientRouter handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>

prefetch('/about', { with: 'fetch' });
prefetch('/about');

  }
</style>
<style>
  body {
    background: yellow;
    background: red;
  }
</style>
<script>
    console.log("hello")
    console.log("world")
</script>
<script>
    console.log("world!")
    console.log("hello!")
</script>

<img style="--fit: <value>; --pos: <value>" >

<img class="__a_HaSh350" data-astro-fit="value" data-astro-pos="value" >

<a href="/sitemap.xml/">Sitemap</a>
<a href="/sitemap.xml">Sitemap</a>

const enabled: boolean = import.meta.env.ENABLED;
const enabled: boolean = import.meta.env.ENABLED === "true";

const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;

interface ImportMetaEnv {
  readonly PUBLIC_POKEAPI: string;
  readonly DB_PASSWORD: string;
  readonly ENABLED: boolean;
  readonly ENABLED: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

namespace NodeJS {
  interface ProcessEnv {
    DB_PASSWORD: string;
  }
}

---


---
<Image src={myImage} width={400} height={300} fit="contain" />
<Image src={myImage} width={400} height={300} />

<Image src={imageThatMightBeAnSvg} format="avif" alt="example" />

<Image
	src={imageThatMightBeAnSvg}
	format={imageThatMightBeAnSvg.format === "svg" ? "svg" : "avif"}
	alt="example"
/>

---


const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---

<div id="background" data-src={optimizedBackground.src}></div>

<script>
  const src = document.getElementById("background").dataset.src;
  // use src client-side as needed
</script>

## `<Picture />`

<h2 id="picture-"><code>&lt;Picture /&gt;</code></h2>

See [the Picture component](/en/guides/images/#picture-) for more details.

---

{
  hooks: {
    'astro:build:setup': ({ target, vite }) => {
      if (target === 'client') {
        vite.build.minify = false;
      }
    }
    'astro:build:setup': ({ vite }) => {
      vite.environments.client.build.minify = false;
    }
  }
}

server.hot.send(event)
server.environments.client.hot.send(event)

// To retrieve the same format (e.g., "file:///path/to/src"), make the following change:
const srcPath = manifest.srcDir;
const srcPath = manifest.srcDir.href;

const mappings = manifest.serverIslandMappings;
const driver = manifest.sessionDriver;
const mappings = await manifest.serverIslandMappings?.();
const driver = await manifest.sessionDriver?.();

import type { Loader } from 'astro/loaders'

function myLoader(): Loader {
function myLoader() {
  return {
    name: 'my-loader',
    load: async (context) => {
      // ...
    },
    schema: z.object({/* ... */})
  }
  } satisfies Loader
}