astro-knowledge-patch

Astro Knowledge Patch (5.16 – 6.0)

Covers Astro 5.16 through 6.0 (December 2025 – March 2026). Claude Opus 4.6 knows Astro through 4.x. It is unaware of the features below.

Index

Topic	Reference	Key features
Breaking changes	references/breaking-changes.md	Node 22+, removed APIs, Zod 4, Vite 7, Shiki 4
Content & caching	references/content-and-caching.md	Live collections, retainBody, route caching (Astro.cache)
Fonts & assets	references/fonts-and-assets.md	Built-in Fonts API, SVGO optimization, image background prop
Security (CSP)	references/security.md	security.csp config, auto-generated hashes, directives

---

Breaking Changes (6.0)

Change	Detail
Node.js minimum	22+ (dropped 18 & 20)
Removed APIs	Astro.glob(), emitESMImage(), <ViewTransitions /> (use <ClientRouter />)
Content collections	Legacy content collections removed
Zod	Upgraded to Zod 4 (Zod 3 no longer supported)
i18n	i18n.redirectToDefaultLocale default behavior changed
Dependencies	Vite 7, Shiki 4

Built-in Fonts API (6.0)

Configure fonts in astro.config with automatic self-hosting and optimized fallbacks:

import { defineConfig, fontProviders } from 'astro/config';
export default defineConfig({
  fonts: [
    {
      name: 'Roboto',
      cssVariable: '--font-roboto',
      provider: fontProviders.fontsource(),
    },
  ],
});

Use the <Font /> component from astro:assets:

---
import { Font } from 'astro:assets';
---
<Font cssVariable="--font-roboto" preload />
<style is:global>
  body { font-family: var(--font-roboto); }
</style>

Providers: fontProviders.fontsource(), fontProviders.google().

Live Collections (6.0)

Real-time content collections that update without rebuilds:

// src/content.config.ts
import { defineLiveCollection } from 'astro:content';
import { myLoader } from './loader';

const products = defineLiveCollection({
  loader: myLoader({ apiKey: process.env.API_KEY }),
});
export const collections = { products };

---
import { getLiveEntry } from 'astro:content';
const { entry, error } = await getLiveEntry('products', Astro.params.id);
if (error) return Astro.redirect('/404');
---
<h1>{entry.data.title}</h1>

Content Security Policy (6.0)

Astro auto-generates hashes for inline scripts/styles. Simple mode:

export default defineConfig({
  security: { csp: true },
});

Full config at security.csp — see references/security.md.

Route Caching (6.0, experimental)

Platform-agnostic SSR response caching:

import { defineConfig, memoryCache } from 'astro/config';
export default defineConfig({
  experimental: {
    cache: { provider: memoryCache() },
  },
});

---
Astro.cache.set({
  maxAge: 120,
  swr: 60, // stale-while-revalidate
  tags: ['home'],
});
---

Auto-invalidates with live collections:

const product = await getEntry('products', Astro.params.slug);
Astro.cache.set(product); // invalidates when product changes

In API routes, use context.cache instead of Astro.cache.

Image Background Prop (5.17)

Control background color when converting to non-transparent formats:

<Image src={myImage} format="jpeg" background="white" alt="Product" />

Also works with getImage():

const img = await getImage({ src: heroImage, format: 'jpeg', background: 'white' });

Smaller Additions

ActionInputSchema Utility Type (5.16)

Extract input schema from an action definition:

import { type ActionInputSchema, defineAction } from 'astro:actions';
import { z } from 'astro/zod';

const myAction = defineAction({
  accept: 'form',
  input: z.object({ email: z.string().email() }),
  handler: ({ email }) => ({ success: true }),
});

type MySchema = ActionInputSchema<typeof myAction>;

Experimental SVGO (5.16)

Automatic SVG optimization in the asset pipeline:

export default defineConfig({
  experimental: {
    svgo: true,
    // or: svgo: { plugins: ['preset-default', { name: 'removeViewBox', active: false }] }
  },
});

retainBody: false for glob() Loader (5.17)

Reduces data store size by omitting raw body from entry.body:

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog', retainBody: false }),
});

Rendered HTML remains available via entry.rendered.html.

Cloudflare: cloudflare:workers (6.0)

Replaces Astro.locals.runtime for accessing Cloudflare bindings:

---
import { env } from "cloudflare:workers";
const kv = env.MY_KV_NAMESPACE;
const visits = await kv.get("visits");
---

Reference Files

File	Contents
breaking-changes.md	Node 22+, removed APIs, Zod 4, dependency upgrades
content-and-caching.md	Live collections, retainBody, route caching
fonts-and-assets.md	Fonts API, SVGO, image background prop
security.md	CSP configuration and directives