Astro Knowledge Patch

Astro Knowledge Patch

Use this skill when creating, upgrading, integrating, or debugging an Astro project. Check the breaking changes first, then open the topic reference that matches the task. For older projects, keep the version-qualified transition notes in mind instead of applying the newest form blindly.

Reference index

Breaking changes first

Astro 7 checks

• Markdown and MDX use Sätteri by default with GFM enabled. Select unified() explicitly if the project depends on remark or rehype plugins.
• Queued rendering is stable and automatic. Remove experimental.queuedRendering.
• Move cache and routeRules out of experimental.
• Move logger out of experimental and replace --experimentalJson with --json.
• Put a custom standard advanced-routing handler at src/fetch.ts; without that file Astro uses the normal pipeline.

Astro 6 checks

• Use Node.js 22 or later and align pinned packages with Vite 7, Shiki 4, and Zod 4.
• Import Zod from astro/zod, not astro:content.
• Move experimental.csp to security.csp.
• Move experimental.fonts to top-level fonts.
• Replace experimental.svgo with experimental.svgOptimizer and an optimizer implementation.
• Vite 8 belongs to the Astro 7 toolchain; keep Astro 6 projects on Vite 7.

Removed and superseded forms

Markdown processor quick reference

Keep unified when existing plugins must run:

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: {
    processor: unified({ remarkPlugins: [remarkToc] }),
  },
});

Use Sätteri for its Rust pipeline and native feature flags:

import { satteri } from '@astrojs/markdown-satteri';

export default {
  markdown: {
    processor: satteri({ features: { directive: true } }),
  },
};

Sätteri does not execute remark or rehype plugins.

Route caching quick reference

Configure the provider and route rules at the top level:

import { defineConfig, memoryCache } from 'astro/config';

export default defineConfig({
  cache: { provider: memoryCache() },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
});

Set a page policy with Astro.cache.set() and an endpoint policy with context.cache.set(). Use maxAge, swr, and tags; invalidate by tag or path. Passing a live content entry records an automatic invalidation dependency. The in-memory provider mainly suits the Node adapter; platform CDN providers can serve hits without invoking the server function.

Advanced routing quick reference

Compose the request pipeline only when an application needs a proxy or explicit stage ordering:

import { FetchState, astro } from 'astro/fetch';

export default {
  fetch(request: Request) {
    const state = new FetchState(request);
    if (state.url.pathname.startsWith('/api')) {
      return fetch(new URL(state.url.pathname, 'https://api.example.com'));
    }
    return astro(state);
  },
};

astro/fetch and astro/hono expose rendering, redirect, session, Action, middleware, page, cache, and i18n stages. Cloudflare projects should also apply the adapter's cf() helper for bindings, assets, context, and error pages.

Live collections quick reference

Define live collections in src/live.config.ts. They require an on-demand adapter and a custom loader with loadCollection and loadEntry:

import { defineLiveCollection } from 'astro:content';
import { apiLoader } from './loaders/api-loader';

const products = defineLiveCollection({
  loader: apiLoader({ endpoint: process.env.API_URL }),
});

export const collections = { products };

Query with getLiveCollection() or getLiveEntry() and inspect the returned error. Live collections do not persist through the Content Layer and do not support runtime MDX or image optimization.

Fonts quick reference

Configure fonts at the top level; provider assets are downloaded and served locally:

import { defineConfig, fontProviders } from 'astro/config';

export default defineConfig({
  fonts: [{
    provider: fontProviders.google(),
    name: 'Roboto',
    cssVariable: '--font-roboto',
    weights: [400, 700],
  }],
});

Use <Font> to apply or preload a configured family. Read generated URLs from fontData in astro:assets. Repeat a matching family declaration to merge selected non-Cartesian weight and style combinations.

Security and session quick reference

Enable stable CSP with security: { csp: true }. Astro hashes managed inline scripts and styles. On-demand pages use response headers; prerendered pages need adapter static-header support for directives that cannot be represented in a meta element.

Import declared secrets from astro:env/server. Prefer astro:env over direct import.meta.env access when validation, client/server separation, or bundle secrecy matters.

Sessions are available through Astro.session or context session. Type known keys by augmenting App.SessionData. For cookie-less clients, load an explicit ID with session.load(id) and return session.sessionId; set session: false when an SSR application does not use sessions.

Image and SVG checks

• Configure responsive layouts with image.layout and image.responsiveStyles; component values override global defaults.
• priority selects eager loading, synchronous decoding, and high fetch priority.
• Remote image redirects are limited to ten hops, and every hop must remain allowlisted.
• SVG rasterization is disabled by default; enable dangerouslyProcessSVG only for trusted sources.
• Imported SVG components are inline. Use SvgComponent from astro/types when passing them through typed APIs.
• Use experimental.svgOptimizer with svgoOptimizer() for build-time SVG component optimization.

Tooling quick reference

• server.allowedHosts and --allowed-hosts protect dev and preview servers from untrusted Host headers.
• mergeConfig() and validateConfig() support integration-style programmatic configuration.
• build(config, options) accepts devOutput and teardownCompiler.
• astro dev --background and astro preview --background detach after readiness; manage them with their status, logs, and stop subcommands.
• Use astro dev --ignore-lock only for an untracked parallel foreground server.
• Configure top-level logger with logHandlers.json(), console(), compose(), or a custom entrypoint.