Astro 6.3 | Astro

Astro 6.3 is here! This release brings experimental advanced routing, giving you full control over your request pipeline. Compose individual handlers, bring your own framework like Hono, and decide exactly what runs and in what order.

Explore what’s new in this release:

Experimental: Advanced Routing
Support redirects on external image URLs
SVG image processing disabled by default

To upgrade an existing project, use the automated @astrojs/upgrade CLI tool. Alternatively, upgrade manually by running the upgrade command for your package manager:

# Recommended:
npx @astrojs/upgrade

# Manual:
npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest

Experimental: Advanced Routing

Astro 6.3 introduces experimental support for advanced routing: full control over how requests flow through your application, with first-class support for frameworks like Hono.

Your app exports the fetch handler pattern used by Cloudflare Workers, Deno, Bun, and Hono. Proxy certain paths to another service and let Astro handle the rest:

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 normally runs middleware, actions, i18n, and rendering in a fixed order. That works for most projects, but as applications grow you end up working around the framework to add auth, logging, rate limiting, or platform-specific logic in the right place.

With advanced routing, every step of the pipeline is available as its own handler. Mix in your own logic and decide exactly what runs and in what order:

import { Hono } from 'hono';
import { logger } from 'hono/logger';
import { actions, middleware, pages, i18n } from 'astro/hono';

const app = new Hono();

// Your own middleware runs first.
app.use(logger());
app.use(async (c, next) => {
  if (new URL(c.req.url).pathname.startsWith('/admin')) {
    return c.redirect('/login');
  }
  return next();
});

// Astro handlers in the order you choose.
app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());

export default app;

Available handlers include astro, trailingSlash, redirects, sessions, actions, middleware, pages, cache, and i18n, exported from both astro/fetch and astro/hono.

For more information on enabling and using this feature in your project, see the Experimental Advanced Routing docs.

Support redirects on external image URLs

When optimizing remote images, Astro previously failed silently if the image URL returned a redirect. This was a problem for CDNs and image services that use redirects to route requests to the correct edge node or storage bucket. Your images would just disappear from the build without explanation.

Astro 6.3 now follows up to 10 redirects when fetching remote images. Every URL in the redirect chain is validated against your image.remotePatterns and image.domains configuration, so you stay in control of which hosts Astro is allowed to fetch from. If a redirect leads to a host that isn’t in your allowlist, Astro will throw a helpful error instead of silently ignoring the image.

import { defineConfig } from "astro/config";

export default defineConfig({
  image: {
    domains: ["example.com", "cdn.example.com"]
  }
});

---
// Redirects to https://cdn.example.com/assets/image.png - works!
// Redirects to https://malicious.com/image.png - throws an error
---
<Image src="https://example.com/assets/image.png" width="1920" height="1080" alt="An example image." />

If you trust all HTTPS hosts, you can allow them with a single remote pattern:

import { defineConfig } from "astro/config";

export default defineConfig({
  image: {
    remotePatterns: [{
      protocol: 'https'
    }]
  }
});

SVG image processing disabled by default

Astro’s Sharp image service can rasterize SVG files into other formats like PNG or WebP. However, this runs librsvg under the hood, and SVG files can contain embedded scripts and other active content. Processing untrusted SVGs this way is a potential security risk.

Starting in Astro 6.3, SVG image processing is disabled by default. If you pass an SVG source to the image optimization pipeline, Astro will now throw a helpful error instead of silently processing it.

If you trust your SVG sources and want to restore the previous behavior, set the new image.dangerouslyProcessSVG option:

import { defineConfig } from "astro/config";

export default defineConfig({
  image: {
    dangerouslyProcessSVG: true,
  }
});

This change does not affect importing SVGs as components. It only applies to rasterizing SVG sources through the image optimization pipeline (e.g. converting an SVG to PNG via <Image />).

Other improvements

A new consume() method for AstroCookies: this method marks cookies as consumed and returns the Set-Cookie header values. After consumption, any subsequent set() calls will log a warning since the headers have already been sent. This replaces the static AstroCookies.consume(cookies) method, which is now deprecated but kept for backward compatibility with existing adapters.

For a complete list of bug fixes and smaller improvements, see the full changelog.