npm / astro
astro
What changed in astro 5 to 7, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.
124 breaking53 security20 deprecations115 new APIs and options22 performance35 behavior and defaults15 tooling435 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initastro 7328 changes
Breaking changes 40
The glob loader no longer swallows rendering errors during content sync, so astro build fails when remark or rehype plugins throw.
Rendering errors during content sync now cause astro build to fail instead of being swallowed and returning exit code 0.
The minimum supported Node.js version is now 22.22.0.
Prerender errors now fail the build instead of being silently written as empty HTML files.
Malformed JSON action requests now return 400, while malformed percent-encoded action names return 404.
Composable handlers now reject over-encoded request paths with 400 Bad Request, matching astro().
Composable handlers now reject over-encoded request paths with 400 Bad Request, matching astro().
The Node adapter now validates the Host header against security.allowedDomains.
Astro components must be imported with the new query string to use the container renderer.
On Windows with an AI agent detected, astro dev and astro preview run in the foreground unless --background is passed.
The options type now prevents passing
widthsanddensitiestogether.Dynamic values in MDX script and style children are now escaped; use set:html to explicitly render them as raw markup.
The minimum supported version of Sharp is now 0.35.4.
Cloudflare integrations now require Wrangler version 4.125.0 or newer.
Module imports added without a corresponding deferredRender entry are no longer preserved across writes.
Astro CSP no longer emits hashes for directives using unsafe-inline.
The undocumented internal app.pipeline property has been removed; adapters should use app.getLogger() instead.
The AppPipeline export from astro/app has been removed; adapters should use app.getLogger() instead.
Files in directories whose names start with pages are no longer treated as page routes.
Content collection references to missing entries now produce an error after loaders finish syncing.
Removes an unused and undocumented generic parameter from the logger destination type.
The Astro DB CLI command is no longer available.
The Astro init CLI command is no longer available.
The Astro link CLI command is no longer available.
The Astro login CLI command is no longer available.
The Astro logout CLI command is no longer available.
Deprecated transition constants, event guards, and createAnimationScope() can no longer be used.
The Rust-based compiler is now the default, improving build speed and development iteration while enforcing stricter syntax handling.
The unmaintained Astro DB package has been removed and projects must choose another database solution.
The remark/rehype processor is no longer installed by default and must be installed explicitly to use that pipeline.
Route caching is stable and the cache configuration moves from experimental.cache to the top level.
The default is now JSX-style HTML compression, removing surrounding whitespace while preserving meaningful inline spaces.
The experimental queued-rendering setting has been removed because the new rendering engine is stable.
The experimental compiler-selection flag has been removed because the Rust compiler is now default.
The entrypoint setting is now top-level and can be set to a custom file or null.
Route caching rules are stable and routeRules moves from experimental.routeRules to the top level.
Markdown files now use the native Sätteri processor by default instead of the remark/rehype pipeline.
Advanced routing now uses src/fetch.ts as its default entrypoint.
The public advanced-routing provider extension point is now internal-only; integrations should use locals for per-request state.
Astro now supports Vite 8.
Security 14
CSRF protection now takes modern browser headers into account.
Domain-based i18n routing now respects allowed request host domains when selecting a locale.
SVG
<style>elements nested inside<defs>or other containers are now hashed for CSP.Astro: Remote code execution through AVIF image optimization
Non-UUID cookie values are rejected before they are used as storage keys.
Base path stripping now respects path-segment boundaries, keeping routing and context.url.pathname consistent.
Hardens development metadata when embedding dynamic values.
Hardens generated transition styles when embedding dynamic values.
Hardens server island URLs when embedding dynamic values.
Astro: XSS via unescaped spread attribute names in renderHTMLElement (incomplete fix for CVE-2026-54298)
The origin check now applies consistently to Astro Actions and on-demand endpoints across request pipeline compositions.
Forwarded host validation now occurs before trusting X-Forwarded-For for clientAddress, protecting forwarded request handling.
Transition directive values are HTML-escaped when rendered on hydrated islands.
Astro now enforces stricter limits on URL decoding operations.
Deprecations 3
Returning a plain array from getStaticPaths is deprecated because images used on those pages are not generated.
Returning a plain Response from render is deprecated because images used on those pages are not generated.
Deprecation messages now target Astro 8.
New APIs and options 43
The new flag prints build timing summaries to help identify slow integrations, processors, image processing, or syntax highlighting.
Permite conservar el enrutamiento integrado de Astro y añadir preprocesamiento y posprocesamiento personalizados en un solo lugar.
Static pages can be rendered in parallel across CPU cores to reduce build times, with higher memory usage.
Static redirect pages can be customized with a project-provided page for branding or translation.
Font provider init contexts now include a fetch function that requests provider APIs and retries transient failures.
Font providers can expose supported weights, styles, subsets, and formats so Astro can warn about unavailable configuration values.
Image services can now be configured separately for build-time prerendering and runtime on-demand rendering.
The new handler renders the custom 404 page for unmatched routes in astro/fetch and astro/hono integrations.
Custom prerenderers can access the final client, server, and prerender output locations.
Adds a container function that renders Astro components with inlined styles and scripts.
Passing --background explicitly requests an Astro-managed background process.
Adds --ignore-lock so multiple preview servers can run simultaneously on different ports, useful for E2E testing workflows.
Custom cache providers receive Astro's runtime logger in the onRequest context.
Custom image services receive Astro's runtime logger so messages follow the configured destination and log level.
APNG files can be imported as image metadata for standard img elements; image components continue rejecting them to preserve animation.
Adapters can use app.getLogger() to wait for the configured log destination.
Starts preview servers as background processes and returns after the server is ready.
Setting this environment variable to 0 opts out of automatic background mode for preview servers.
Displays logs from a preview server running in the background.
Follows logs from a background preview server.
Inspects a preview server running in the background.
Stops a preview server running in the background.
The render method may return a Response or PrerenderResult containing metadata for incremental static builds.
A cacheKey can identify generated pages from getStaticPaths() for incremental static builds.
Content collection entries optionally expose a loader-provided digest to detect content changes without re-hashing entry bodies.
Enables experimental incremental static builds that skip unchanged pages from dynamic routes.
Adds session: false to opt out of session support.
Adds a chunkSize setting to control the size of chunks used by collectionStorage.
Allows a development server to run without checking or writing the project lock file.
Adds chunked persistence for large content layer data stores to avoid platform file-size limits.
Adds deferred rendering for renderable content entries, reducing memory usage during large astro build operations.
Allows the logger entrypoint to be configured with a URL.
Allows CSP resources and hashes to target element-specific or attribute-specific script and style directives.
The AstroRuntimeLogger interface is now exposed so runtime logger functions can be typed properly.
Shared helpers are exported for CDN cache provider authors to build headers, invalidation tags, and normalized options.
The new flag starts the development server as a detached background process.
Setting this environment variable to 0 opts out of automatic background mode when an AI coding agent is detected.
A new subcommand displays logs from a background development server and can stream new output.
A new subcommand reports whether a development server is running, including its URL, PID, and uptime.
A new subcommand stops a running background development server.
Cache providers now receive the incoming Request as a second argument when generating response headers.
FontData entries now expose the subset name so applications can distinguish font entries sharing weight and style.
getFetchState() is now public from astro/hono, allowing custom Hono middleware to access Astro per-request state.
Performance 12
The dev server no longer re-evaluates the whole server module graph on every request.
Startup is faster because content configuration and app module graphs compile during server creation without blocking listening.
Rendering performance improves.
Improves build performance for sites with many pages originating from many different modules.
Each route is deserialized only once when loading the SSR manifest.
The local Astro CLI uses Node's module compilation cache to improve performance.
No-op pathname writes are skipped when normalizing SSR request URLs.
Incremental builds are no longer prohibitively slow for sites with many pages or content entries sharing a large dependency graph.
getCollection() is faster for entries without local image references.
getEntry() is faster for entries without local image references.
The session runtime and unstorage dependencies are tree-shaken when no session driver is configured, reducing SSR bundle cold-start parsing.
Rendering is faster for pages with many component instances, including repeated MDX Content components.
Behavior and default changes 16
Custom prerenderers can return image metadata from getStaticPaths so Astro generates images used on prerendered pages.
Dynamic routes in static mode must export getStaticPaths() to return every path that should be generated at build time.
Dev mode uses path-based class name hashing so CSS edits do not change generated selectors or require a full reload.
YAML parsing now supports timestamps and merge keys, with consistent errors across Astro, Markdown, MDX, and Markdoc.
On Windows, the command runs in the foreground when an AI agent is detected, allowing the agent to manage its process lifetime.
Incremental builds support concurrent rendering, including when using @astrojs/cloudflare.
Remaining internal warnings and errors use the configured logger instead of writing directly to the console when possible.
Generated and default Cloudflare compatibility dates now match the installed runtime.
Package manager detection for install commands now recognizes the devEngines field in package.json.
Accepts paths relative to the project root, while package specifiers, absolute paths, and URL entrypoints continue working.
URL-safe cookie values are no longer percent-encoded, while encoded values continue to round-trip exactly as before.
Generated image styles now use
@layer astro.images, giving user-defined CSS layers higher cascade priority.Advanced routing is now stable and enabled by default.
context.logger is now always defined in API routes and middleware, even without custom logger configuration.
The experimental advanced-routing flag should be removed because the feature is enabled by default.
Rendering now streams components as they are encountered and flushed instead of constructing a queue.
Tooling 4
Astro CLI commands can now install tagged package versions.
The TypeScript 7 error now explains the unsupported status and provides experimental type-checking instructions.
Editing action files during development now applies on the next request without restarting the dev server.
The development server writes a lock file containing its URL, port, and PID to prevent duplicate servers.
Fixes and other changes 196
Original images are no longer retained when only width or height is read.
Deployment integrations can use Vite manifests when preparing build output.
Preserves existing allowBuilds approvals in pnpm-workspace.yaml when using pnpm v11.0–v11.22.
Astro.cache is no longer undefined when a custom 404 or 500 page is rendered by the error handler.
The glob() loader now reloads changed files in development when patterns start with an extglob.
Dependency installation failures now display the package manager's error output.
The command now installs dependencies successfully with pnpm v11+ by approving the workerd build script.
The configured cache provider is registered before rendering, making Astro.cache available to downstream handlers such as pages().
The cache() handler no longer throws a TypeError when a cache provider is configured.
AVIF images are served with the correct image/avif MIME type instead of image/heif in the dev server.
The layout frontmatter property is ignored for content collection entries, preventing a build error with deferred glob rendering.
Origin checks no longer reject cross-origin requests with non-form content types such as application/json.
Prevents intermittent dev server crashes when used inside a server island with adapters using a pre-bundled SSR environment.
Prevents Windows builds with Node.js 25+ from failing when clearing the output directory encounters a transient EPERM error.
Prevents CSS from other pages leaking into a page's head during development.
Dependency scanning no longer fails when an Astro file contains a literal script tag in frontmatter or a template expression.
Request cookies with empty values no longer produce undefined.
Astro.rewrite no longer selects the wrong route in astro dev when two dynamic routes match the same path.
Production builds no longer duplicate CSS when a component is server-rendered and also used with client:only.
Preserves request state when Vite discovers server dependencies during a request.
Content collection changes are no longer ignored in astro dev after a configuration-triggered server restart.
context.props is no longer null in middleware and endpoints for specified composable handler ordering.
context.rewrite no longer selects the wrong route in astro dev when two dynamic routes match the same path.
CSS Module HMR now works when a component is rendered both hydrated and non-hydrated on the same page.
Preloaded CSS files no longer return 404 when the imported module uses a component also hydrated as an island.
Rendered output no longer includes dev toolbar source attributes when components are rendered under Vitest.
Fixes type errors in Astro's built-in Font component when type-checking with tsc and the content mapper.
The fontsource provider now resolves variable fonts when the font name uses the Variable suffix.
The glob loader no longer skips content files whose paths contain hash or question-mark characters.
Composable i18n handlers now render the custom 404 page for paths without a locale prefix.
Routes added with injectRoute now work without a locale prefix when this option is enabled.
Injected routes without locale prefixes no longer return 404 when the default locale is prefixed.
CSS imported from a page injection script is no longer dropped during builds.
Localized error pages now return their error status instead of 200 through the pages handler.
Fixes type errors in Astro's built-in Picture component when type-checking with tsc and the content mapper.
Prevents stale scoped styles during HMR when markup and style change together.
Prevents hangs when a deferred component is inside another component's slot in an MDX content collection entry.
Framework components inside server islands no longer render empty in the dev server with a custom fetch file.
The server manifest assets array now has deterministic ordering, producing byte-identical builds from identical inputs.
Astro now works in StackBlitz and other WebContainer environments.
Removes a stale directive that caused MODULE_LEVEL_DIRECTIVE warnings during builds.
Muted video elements no longer lose their muted state after ClientRouter navigation in Chrome.
Custom direction names that are invalid CSS identifiers now match their animations correctly.
Responsive image styles no longer emit invalid object-position values for same-axis keyword pairs.
Unchanged pages are no longer repeatedly rendered when bundled assets are referenced by modules or compiled CSS.
Ampersands in Markdown image alt and title attributes are escaped exactly once in final HTML.
The dev overlay now shows the documented unsuffixed error name instead of a name ending in Error.
The dev overlay now shows the documented unsuffixed error name instead of a name ending in Error.
The dev overlay now shows the documented unsuffixed error name.
Importing
astro:actionsin Cloudflare Vitest pool worker tests no longer causes a WebAssembly error.Writes outside the module graph no longer invalidate middleware and trigger repeated SSR reloads.
Renderer server entrypoints and the default console logger are pre-bundled during dev, preventing mid-request re-optimization crashes on Cloudflare.
The flag now starts preview or dev servers in the foreground in AI agent environments unless
--backgroundis also specified.Locale matching now handles casing differences and underscores for object-form locale configurations.
Development URLs that merely share a prefix with the configured base are no longer incorrectly rewritten.
Content collection HMR now updates prerendered pages when adapters use a separate prerender environment.
CSS HMR now works for framework components rendered through content entries after
ClientRouternavigation.Custom dev toolbar app UIs now persist through client-side navigation with
<ClientRouter />.MDX files are included in dependency scanning so framework dependencies are bundled before runtime, preventing an initial page reload.
Restored pages no longer retain stale CSS after preprocessor changes or missing original images.
TypeScript autocompletion now suggests all available predefined options.
Deleted files are removed from the content data store, and new files in empty collections are detected without restarting.
Invalid and missing local image paths now return appropriate 400 and 404 responses.
Prerendered Cloudflare pages no longer render as
[object Object]whennodejs_compatis enabled.Dynamic route parameters containing
$replacement patterns no longer corrupt redirect targets.Redirect response HTML now points to the corrected trailing-slash target and preserves the query string.
Generated CSS now serializes transition animation values more reliably.
Prevents a 504 Outdated Optimize Dep error when workspace-linked packages import dependencies missed by Vite's initial scan.
Fixes sessions breaking in dev mode when using the Cloudflare adapter with middleware.
Fixes an error that prevented projects using astro:assets from starting or building.
Incremental builds no longer disable caching when build.concurrency is greater than 1, so the workaround setting it to 1 can be removed.
Fallback routing now replaces the actual locale segment instead of the first matching substring, preventing mangled paths.
The memory cache provider now skips responses with Vary: Cookie or Vary: *.
Restores missing styles, links, and scripts from content collection entries rendered inside server islands.
The package is no longer pinned to an exact version, allowing compatible version resolution.
Cached responses containing Last-Modified or ETag validators are handled correctly by browser heuristic caching.
Editing entries during astro dev on Windows now refreshes served content without restarting the dev server.
Runtime logger initialization in development is corrected.
Images no longer render an empty srcset attribute when no responsive candidates are generated.
Warnings correctly identify the route that first rendered a duplicate pathname instead of an unrelated matching route.
The placeholder is replaced correctly in minified server builds, preventing an Invalid URL crash at server boot.
SSR manifests no longer reference prerender-only chunks absent from final build output.
.htmlimports are now typed outside.astrofiles.Requesting
/index.htmlno longer crashes against a dynamic page route.set:textescaping now works correctly in MDX script and style elements.next now works for GET and HEAD requests with host-provided bodies.
rewrite now works for GET and HEAD requests with host-provided bodies.
Route selection now works correctly for normalized request paths in adapters and development request handling.
The experimental svgOptimizer now generates unique per-file ID prefixes with SVGO's prefixIds plugin.
Fixes development failures when creating FetchState with a request while server dependencies are optimized.
CLI flags are preserved when running the development server in the background.
Accept-Language quality values are honored, including implicit quality 1.0 and q=0 rejection.
Locale selection now honors Accept-Language quality values regardless of header order.
Wrapped plugin errors now show the correct file location, line and column, and hints.
A regression that could prevent content collection images from being resolved is fixed.
The development server can restart in Docker containers without failing due to PID reuse in the lock-file check.
Valid font URLs are no longer rejected when using the Cloudflare adapter.
i18n rewrite fallback returns 404 instead of 500 when no matching prerendered static path exists.
The content loader now loads files whose names contain colons.
The image() schema now includes apng so content collection images match imported image types.
Stylesheet-only edits no longer serve cached HTML referencing stale CSS filenames.
Responses that set cookies through Astro.cookies or Astro.session are no longer stored.
Deferred components importing from astro:i18n no longer crash the development server.
Persisted transitions work again for audio and video elements.
User configuration for ssr, prerender, and client environments is now properly deep-merged with Astro's internal settings.
User-provided environment settings are deep-merged with Astro's internal settings instead of breaking server entry naming.
Builds no longer hang when an image file is malformed.
Astro.site is now available when rendering components through the Container API if site is configured.
Dynamic routes no longer throw Missing parameter with build.format preserve and trailingSlash always.
Composable request helpers no longer throw when used on requests rewritten with Astro.rewrite() or next().
If a configured logger fails to load, Astro reports the error and continues with the default console logger.
The dev server now recognizes route changes after pages are added, removed, or renamed without requiring a restart.
Prevents out-of-memory errors when chunked collection storage receives multiple concurrent updates to the same collection.
new FetchState(request) now works anywhere inside a built Astro server, including custom src/fetch.ts entrypoints.
getCollection() no longer throws DataCloneError when collection schema transforms return Temporal.PlainDate or other class instances.
getEntry() no longer throws DataCloneError when collection schema transforms return Temporal.PlainDate or other class instances.
Requests with malformed ports in the Host header now fall back to a server-controlled host instead of throwing.
SSR full reloads triggered by third-party Vite plugins no longer fail to load astro:server-app.js.
astro dev now cleans stale lock files after Docker restarts and avoids signaling unrelated processes when --force is used.
Incremental builds no longer drop optimized images for cached pages when using a collectStaticImages prerenderer.
Component styles from content entries no longer remain stale until a second save in Astro's fallback development environment.
The Fonts API no longer breaks experimental.incrementalBuild caching because generated dependency-hash code uses a build-local server port.
Builds reduce intermittent ImageNotFound errors on projects with many images by limiting concurrent reads and retrying transient I/O failures.
The setting now applies to duplicate ID warnings from glob() and file() content loaders, throwing for 'error' and suppressing warnings for 'ignore'.
CSS hot module replacement now works after navigating between pages with ClientRouter.
Builds no longer fail because generated content collection image import identifiers collide.
Incremental builds no longer re-render unchanged routes that import multiple assets.
Middleware HMR now reloads when imported modules change, not only when the middleware file itself changes.
CSP no longer rejects speculation rules when security.csp and experimental.clientPrerender are used with data-astro-prefetch links.
Video and audio elements remain functional after navigation via view transitions.
Avoids crashing with Invalid URL when --host uses a specific non-loopback address.
Preserves cookies set inside custom 404.astro or 500.astro error pages in the final response.
Returns the correct .html pathname for non-index pages when build.format is preserve.
Prevents a build crash when an older hoisted neotraverse version is present at the project root.
Returns only requested glyphs instead of the full icon font when multiple experimental glyphs are specified.
Boolean popover values on custom elements render as a bare attribute or are omitted, instead of popover="true" or popover="false".
Prevents stale CSS after editing component style blocks and CSS files during development.
Concurrent static builds now generate i18n rewrite fallbacks correctly for dynamic routes.
Resolved action function properties are no longer incorrectly treated as routable path segments.
Custom error pages now render after middleware rewrites target routes returning empty 404 or 500 responses.
Custom logger.entrypoint values now load correctly at runtime in built server bundles.
Errors while finalizing a request no longer prevent a response from being sent.
Session runtime errors now route through Astro's logger instead of being silently swallowed by console.error.
TypeScript path aliases from tsconfig.json now resolve correctly in astro.config.ts.
The background prop is now included in Image and Picture component types, preventing astro check errors.
Scoped styles for child components inside client:only islands are now included in production builds.
Server output now emits one shared stylesheet when prerendered and server-rendered pages use the same CSS source modules.
glob loader watcher negation patterns now exclude matching files during development as they do during the initial scan.
A storage failure during session regeneration no longer leaves the session partially initialized or causes unnecessary later storage reads.
Background dev servers on Windows no longer open a visible terminal window or steal focus.
astro build now respects container CPU limits during image optimization, reducing peak memory usage and preventing out-of-memory crashes.
Mutations to Astro.locals during the request lifecycle are now preserved and passed to custom error pages.
The fetch fallback for prefetch now catches rejected requests in WebKit, preventing flaky connections from causing unhandled promise rejections.
Encoded request paths are now routed correctly when using domain-based i18n.
Fixes crashes in non-Node runtimes by using console logging instead of process stdout and stderr.
Preserves existing behavior for configured script and style resources when using element-specific CSP directives.
Fixes integrations being unable to update the logger configuration.
Fixes browser navigation returning 404 for assets imported with the ?url query.
The first browser visit after starting astro dev no longer triggers an immediate full page reload.
Client islands now recover from transient component import failures instead of permanently failing to hydrate.
The compiler was updated to fix multiple regressions.
The --force flag now replaces an already-running development server.
The --open flag now opens a browser when using an adapter with a custom preview entrypoint.
Fixes a dev server memory leak that caused Node.js warnings in the console.
Keeps CSS @import rules at valid positions after inline CSS chunks are merged during build.
Inlined scripts with ignored dynamic URL imports no longer fail at runtime because of unresolved Vite preload markers.
Fixes CSS module scoped-name hash mismatches in astro dev when using Lightning CSS with content collections.
astro check now finds @astrojs/check and typescript when Astro is installed outside the project tree.
Scripts inside components rendered through Astro.slots.render() remain next to their component content.
Attribute rendering is now handled more robustly when working with custom elements.
getViteConfig no longer crashes in Vitest browser mode because Astro skips dev server setup inside Vitest.
Using the Container API no longer produces a false deprecation warning for markdown.gfm.
Using the Container API no longer produces a false deprecation warning for markdown.smartypants.
Dynamic route parameters with the value 0 are now generated correctly instead of causing a missing-parameter error or being dropped.
Remote image dimensions are resolved once per render, avoiding failures when image servers rate-limit requests.
Live collection entries now expose the correct render() type overload when only live.config.ts is present.
Virtual style modules now include their CSS in dev mode when JavaScript is disabled.
Allows the background dev server to start when astro is hoisted outside the project's node_modules.
Preserves head elements after page transitions when the head contains a server:defer component.
Prevents requests from failing after adapter-based dev server restarts due to missing pre-bundled dependencies.
Restores prefetching for links inside server:defer components.
Prevents component style tags from being silently dropped when an await appears before the component in an .astro file.
The development toolbar now warns when implicit and manually specified ARIA roles are duplicated.
getCollection() no longer returns empty in dev mode for large content collections with 500k+ entries.
Dynamic file endpoints in dev mode no longer incorrectly require a trailing slash when trailingSlash is always.
An error in one route's getStaticPaths no longer prevents other valid routes from matching in dev mode.
Localized custom error routes such as /pt/404 are now used for missing localized pages and return the correct status code.
Background server output and
astro dev statusnow show every exposed network URL.Background development server startup no longer fails on Windows with a process spawn error.
Hybrid environments like Warp are no longer treated as AI agents for auto-background detection.
Advanced-routing pages() and middleware() handlers now render the custom 500.astro page when rendering or middleware throws.
The custom 500.astro page now receives the error prop when the error originated in middleware.
The --port flag is now preserved after a Vite-triggered server restart.
Astro.session is always defined, and accessing it without configured session storage logs a helpful message.
Internationalized domains no longer return 404 when trailingSlash is set to never.
Prerendered routes no longer emit a spurious Astro.request.headers warning when allowedDomains is configured.
astro 6384 changes
Breaking changes 70
Invalid HTML attribute names are now dropped instead of being accepted.
Redirect parameter mismatches now produce a clear InvalidRedirectDestination error during config validation.
isRemotePath() now rejects control characters after a leading slash.
Double-encoded URL paths now receive a 400 response instead of partially decoding silently.
SVG inputs are no longer rasterized by default; this flag opts back into processing them.
Remote image optimization now follows redirects and validates every redirected URL against configured patterns or domains.
The
svgoexperimental flag is removed and superseded byexperimental.svgOptimizer.Style persistence is limited to styles from Vue components instead of automatically persisting all style sheets.
Temporary support for the documented Node.js version range is removed because Stackblitz now uses Node 22 by default.
Requests using prototype method names such as constructor or toString as action paths now return 404.
Removes the old app.render() signature.
Removes exposed astro:actions internals.
The add command and --add option now accept only valid npm package names, preventing possible command injection.
Astro components can no longer be rendered in Vitest client environments.
Removes the unused astro:ssr-manifest virtual module.
Types for the removed astro:ssr-manifest module are no longer provided.
Introduces astro/zod as the preferred source for schema utilities.
X-Forwarded-For is used only after the request host matches security.allowedDomains; otherwise the socket remote address is used.
Removes the previously deprecated Astro.glob().
The Rust compiler requires installing
@astrojs/compiler-rsseparately.Replaces the self adapter entryType value.
Removes support for CommonJS configuration files.
URLs with multiple leading slashes are normalized to one slash before middleware receives them.
The
astro/app/nodemodule exports a utility converting Node incoming messages into web-standard requests.The cssesc dependency was removed and replaced with an ESM-friendly built-in implementation, avoiding occasional CommonJS-related errors.
Removes the function signature for defining dynamic schemas in content loaders.
Removes the deprecated emitESMImage() function.
Endpoint URLs with a file extension cannot be accessed with a trailing slash.
Renames the adapter entryType property to entrypointResolution.
Removes entryPoints from the astro:build:ssr integration hook.
The experimental CSP configuration flag is removed and must be replaced with security.csp.
The experimental fonts configuration flag is removed and replaced by the top-level
fontsoption.The experimental Fonts API now downloads only woff2 files by default; formats can be specified explicitly.
The experimental live collections flag must be removed because live content collections are now supported directly.
Replaces the legacy-dynamic adapter entryType value.
Throws an error when getImage() from astro:assets is called on the client.
Removes the handleForms prop from the ClientRouter component.
Fallback middleware now triggers only for 404 responses instead of intercepting redirects, forbidden responses, and server errors.
Changes the default value of i18n.routing.redirectToDefaultLocale from true to false.
import.meta.env values are always inlined.
Changes integration hooks and HMR access patterns in the Integration API.
Removes legacy content collection support.
Changes how IDs are generated for Markdown headings.
Adapters can specify middleware mode using
middlewareMode, including the'edge'value.The minimum supported Node.js version increases to 22.12.0.
Changes the values allowed in params returned by getStaticPaths(); numbers are no longer allowed.
Routes containing percent-encoded percent signs such as %25 are no longer supported.
Replaces experimental.failOnPrerenderConflict with prerenderConflictBehavior.
An exposed internal API of the preview server is removed.
The development server now blocks direct URL access to files outside srcDir and publicDir.
Removes rewrite() from the Actions context.
Removes RouteData.generate from the Integration API.
Removes routes from the astro:build:done integration hook.
script and style tags render in the order they are defined.
Replaces the experimental CSP flag with a stable security configuration option.
Server actions now enforce a default request body size limit to prevent oversized requests from exhausting memory.
A session cookie without matching server-side data now causes a new session ID to be generated.
Session drivers are now configured as objects created by provider helpers such as
sessionDrivers.redis().Removes setManifestData from App and NodeApp.
Updates the shiki dependency to v4.
Changes SSRManifest property shapes and adds required properties in the Adapter API.
The adapter feature formerly named
experimentalStaticHeadersis now configured asstaticHeaders.Removes the session test driver.
Removes the deprecated ViewTransitions component.
Astro rejects envPrefix entries that match secret environment variables, preventing exposure in client-side bundles.
Astro 6 upgrades to Vite v7.0 as the development server and production bundler.
Removes the with option from prefetch().
The
astro/app/nodemodule exports a utility streaming web-standard responses to Node server responses.X-Forwarded-Proto is trusted only when security.allowedDomains is configured.
Astro 6 upgrades schema validation to Zod v4.
Security 25
Astro: Authorization Bypass via Decode Iteration Limit and Rewrite Path Canonicalization Mismatch
Prerendered error page requests now validate the origin and use the original origin only when the Host header matches configured allowed domains.
Astro: XSS via Unescaped Attribute Names in Spread Props
Astro.request.url now reflects validated forwarded protocol and host headers when security.allowedDomains is configured, keeping it aligned with Astro.url.
The position prop on Image and Picture no longer breaks Content Security Policy.
Slot names on hydrated components are HTML-escaped in SSR output to prevent reflected XSS.
The configuration is respected by astro preview with the Cloudflare adapter, preventing DNS rebinding attacks when previewing Cloudflare builds locally.
Prevents encrypted data from one island component being replayed against a different island component.
Export resolution and hydration error handling are hardened for malformed component metadata.
The error overlay avoids unsafe HTML insertion, reducing security risks when displaying errors.
Server logging avoids unsafe format-string interpolation when handling error-related output.
The endpoint validates that the source is actually SVG before serving content as image/svg+xml.
Astro: XSS in define:vars via incomplete </script> tag sanitization
Makes CSRF origin checking work in astro dev behind TLS-terminating reverse proxies and respects security settings in development.
Duplicate slashes in target paths are collapsed before URL parsing, preventing protocol-relative URL interpretation.
Style tags inside SVG components are correctly tracked when content security policy is enabled.
Server island POST endpoint validation now uses own-property checks for improved consistency.
clientAddress handling now correctly processes multiple header values and rejects values containing invalid IP-address characters.
Catch-all redirect parameters are hardened to prevent protocol-relative URLs in the Location header.
Internal and framing headers are no longer leaked or carried from the original response when rendering error pages.
Allowlists are now enforced when handling remote images.
Responsive images now work with
security.cspby generating hashed build-time styles instead of runtime style elements.The development server validates Sec-Fetch metadata headers to restrict cross-origin subresource requests.
Server island POST endpoints now enforce a configurable request body limit, defaulting to 1 MB.
Decoded backslashes are normalized consistently so middleware and the router see the same canonical pathname.
Deprecations 16
The static cookie consumption method is deprecated but remains for adapter compatibility.
The dev server warns when Vite 8 is hoisted at the project top level because Astro requires Vite 7.
Deprecates astro:schema.
Deprecates exposed astro:transitions internals.
Deprecates Astro in getStaticPaths().
Deprecates createExports() in the Adapter API.
The adapter feature
edgeMiddlewareis deprecated and should be replaced withmiddlewareMode.Deprecates import.meta.env.ASSETS_PREFIX.
Deprecates loadApp() from astro/app/node.
Deprecates loadManifest() from astro/app/node.
Deprecates NodeApp from astro/app/node.
Deprecates the string signature for session drivers.
Specifying a session driver as a string is deprecated in favor of the driver object shape.
CSP and Shiki syntax highlighting are incompatible because Shiki uses inline styles; Astro now warns when both are enabled.
Deprecates start() in the Adapter API.
Deprecates z from astro:content in favor of astro/zod.
New APIs and options 51
Allows projects to replace the default unified Markdown processor with an alternative processor.
Adapters can preserve the dist/server/ directory structure for static builds, matching preserveBuildClientDir.
The satteri() processor can be imported and configured as an alternative Markdown processor.
Adds an interface for typing custom context providers on Astro and ctx.
Adds fetchFile to customize or disable the advanced routing entrypoint file.
Adds a type export for typing the advanced routing entrypoint.
Adds response, automatically set after pages() or middleware() completes.
Provides a low-level Fetch-based API for composing Astro request handlers.
Adds an AstroCookies instance method that marks cookies consumed and returns Set-Cookie header values.
Enables custom control over Astro's server request handling pipeline through a project entrypoint.
Becomes the entrypoint for all server-rendered requests when advanced routing is enabled.
Supports the
jsxvalue, which strips whitespace using JSX rules instead of the default HTML compression strategy.The new astro:assets helper resolves font file URLs from fontData, simplifying font access during development and prerendering.
Experimental configurable log handlers let users replace default console output with built-in or custom logging implementations.
Enables automatic optimization of imported SVG components for smaller file sizes and better performance.
Adapters can forward runtime background-task hooks to Astro, allowing cache providers to perform work such as stale-while-revalidate without blocking responses.
Exposes i18n fallback routes through IntegrationResolvedRoute for integrations using the astro:routes:resolved hook.
Supports codec-specific Sharp encoder defaults for compile-time image generation, while per-image quality still takes precedence.
Accepts an options object for fine-tuning punctuation, dash, ellipsis, and quote transformations in Markdown.
Adapters can collect prerenderable paths from within a target runtime using the new virtual module.
Lets .astro pages set server-rendered response caching directives.
The Node standalone adapter can limit request body size in bytes; the default is 1 GB and
0disables the limit.CacheLike exposes whether caching is active, allowing libraries to avoid conditional try/catch logic.
Purges cached entries by tag or path.
The
<Code />component can highlight embedded languages in addition to its primary language.Live content collection loaders now receive the collection name in their parameters.
Lets API routes and middleware set and inspect server-rendered response caching directives.
Adapter createApp() accepts streaming, enabled by default, allowing adapters to disable HTML streaming when required.
Middleware and adapters can explicitly provide the client IP address to request context.
Adds createSchema() as the equivalent replacement for function-based dynamic schemas in content loaders.
Integration authors can emit assets that move to the client directory during SSR builds.
Enables experimental route caching by configuring a cache provider for on-demand rendered responses.
Queued rendering can cache node values during rendering for reuse.
Projects can opt into a queue-based rendering engine with potential speed and memory improvements.
Queued rendering can reuse a configurable pool of nodes during static page rendering.
Defines default route cache options declaratively, with per-route cache settings able to override them.
Projects can opt into an experimental Rust-based Astro compiler with faster builds and stricter HTML handling.
The Fonts API can load fonts from installed NPM packages or a CDN through the new provider.
Astro adds a first-party Fonts API supporting local fonts and built-in providers with optimization features.
Image services can override remote image metadata retrieval for caching or provider-specific dimension APIs.
This migration flag restores v5 legacy content collection behavior, including automatic loaders, legacy config locations, entry APIs, and path-based IDs.
Content collections can fetch data at runtime through live loaders without rebuilding the site.
Provides a built-in in-memory LRU runtime cache provider with invalidation, stale-while-revalidate, and query filtering support.
Configures whether conflicting prerendered routes error, warn, or silently choose the highest-priority route.
Adapters can preserve client/server directory structure for static builds by opting into this feature.
Content loaders can resolve relative Markdown image paths and populate
metadata.localImagePaths.renderMarkdown() extracts frontmatter into metadata.frontmatter and excludes it from the HTML output.
Astro Actions request bodies can be configured above the default 1 MB limit.
Adapters using
entryType: 'self'can specify a custom server entrypoint.Adapters can provide custom prerendering logic through the
astro:build:starthook.The default Sharp image service can convert SVGs to raster formats such as PNG and WebP.
Performance 8
SSR manifests omit inline CSS for prerendered routes, reducing SSR entry size and cold-start parse time.
Requests without a session cookie no longer initialize storage or perform guaranteed-miss reads.
The dev server caches internal dependency crawling, slightly improving development-server performance.
Server rendering performance for .astro components improves by up to 2x, especially for component-heavy or text-heavy pages.
Astro's installation size is reduced by around 8 MB.
Build memory usage is reduced by filtering routes per environment so each environment builds only the pages it needs.
Returns a cached highlighter based on Shiki options instead of creating a new instance every time.
SSR renderers are no longer bundled when only API endpoints are dynamic.
Behavior and default changes 13
The static preview server is skipped when an adapter supplies previewEntrypoint, allowing the adapter to handle static and dynamic routes.
New Cloudflare projects use today’s date for compatibility_date instead of resolving it from locally installed packages.
The client router skips its animations when the browser already provides a visual transition, such as a swipe gesture.
The command uses the latest valid compatibility_date in the Wrangler configuration when available.
Astro.csp can be undefined when CSP is not enabled, and its methods no longer throw.
Content collection loaders can now use await import() and import.meta.glob() during build.
context.csp can be undefined when CSP is not enabled, and its methods no longer throw.
Astro’s
<Image>output no longer emits redundantfetchpriority="auto"attributes by default.The Node version requirement is lowered to support running on Stackblitz until it supports v22.
Changes how styles for responsive images are emitted.
Content loader schema types are inferred instead of generated.
session.driver is optional because adapters can provide default session drivers.
SSR builds now move only actual client assets, leaving server-side modules such as .sql files in place.
Tooling 5
Generates a Wrangler configuration file with a JSON schema.
Build-time printing is improved when builds take longer than 60 seconds.
The welcome message now highlights the graceful dev/preview server quit command instead of the kill process shortcut.
The command now configures Cloudflare types and adds a
generate-typespackage script.Changes the required or supported TypeScript configuration.
Fixes and other changes 196
Improves diagnostics emitted when Astro parses incorrect .astro files.
Prevents CSS from client:only islands leaking to unrelated pages.
Honors compressHTML when joining head elements.
Restores support for numeric IDs in YAML frontmatter references.
Iteratively decodes multi-level percent-encoding before middleware and route matching instead of rejecting such URLs with 400.
Strips trailing slashes when trailingSlash: 'never' is configured.
Strips trailing slashes when trailingSlash: 'never' is configured.
Strips trailing slashes when trailingSlash: 'never' is configured.
Updates inline style tags in server-rendered HTML after CSS files change during development.
Prevents prerendered redirect targets from being bundled into the SSR function in hybrid mode, reducing bundle size inflation.
Preserves children's slot attributes on custom elements in MDX for correct Shadow DOM named slot distribution.
Triggers HMR for files inside src/middleware/ during development.
Renaming an image while the dev server runs now hot-reloads correctly without triggering a build error or crashing.
The logger destination now applies to the “Server listening on...” startup message because the logger resolves before the server starts listening.
Runtime detection was reverted to avoid a significant build-time regression for Cloudflare adapter users with large prerendered sites.
App.match() no longer throws when request paths contain an invalid percent-sequence.
Astro.currentLocale now returns the mapped domain's locale on dynamic routes instead of the default locale.
Astro.routePattern now preserves the original casing of dynamic parameter names from filenames.
Dynamic routes no longer return a 500 Missing parameter error when using domain-based i18n routing in SSR.
Dynamic routes no longer return [object Object] instead of the expected content in certain runtimes.
Editing client-side components during development no longer causes an unnecessary full backend program reload.
Static file endpoints with .html in dynamic parameter values no longer fail with NoMatchingStaticPathFound during build.
Removes a false middleware warning when astro() is used in a custom src/app.ts and the first request is a redirect route.
Prevents false accessibility warnings for anchors inside closed details elements.
Unmatched routes with astro/hono handlers now render the custom 404 page instead of throwing a TypeError.
Improves optimized fallback generation for bold font variants by using better metrics.
Restores redirectToDefaultLocale functionality after the Advanced Routing refactoring.
Fixes a plugins is not iterable crash when pre-6.0 @astrojs/mdx is used alongside integrations configuring rehype plugins.
Fixes a plugins is not iterable crash when pre-6.0 @astrojs/mdx is used alongside integrations configuring remark plugins.
Fixes a plugins is not iterable crash when pre-6.0 @astrojs/mdx is used alongside integrations configuring remark-rehype plugins.
SSR dynamic routes no longer return 404 when a matching prerendered dynamic route is sorted first and cannot serve the request.
Fixes a dev-mode race condition where the Vite dependency optimizer could lose React dependencies.
Internal routes such as server islands are exempt from getStaticPaths validation, fixing server-island rendering on static sites.
Static preview now serves files from build.client when the adapter requires preserveBuildClientDir.
Preview now accounts for SSR routes discovered during route scanning instead of always using the static preview server.
Forwarded host and protocol headers set by a custom src/app.ts fetch handler are now respected before FetchState creation.
Dynamically imported JavaScript chunks no longer return 404s when adapters use assetQueryParams.
Production builds now include CSS for conditionally rendered Svelte components.
Scoped styles from Astro components rendered through MDX named slots are now retained.
A false-positive warning is no longer logged on every SSR request for dynamic routes.
The astro:i18n module can again be imported from client script blocks after a v6 regression.
Hyphenated custom elements in MDX now use registered renderers during SSR, falling back to raw HTML when unclaimed.
Dynamic routes no longer return 400 Bad Request when URLs contain a literal percent character.
Node adapter now passes Buffer, Uint8Array, and ArrayBuffer request bodies through directly instead of JSON-stringifying them.
The minify option is now forwarded to client-side builds, unless a client environment override takes priority.
Rollup output options are now forwarded to client-side builds, unless client environment overrides take priority.
The sourcemap option is now forwarded to client-side builds, unless a client environment override takes priority.
Empty markdown image alt text is preserved as alt="" in rendered HTML, supporting accessible decorative images.
HMR no longer serves stale content for dynamically imported components routed through barrel files.
The file content loader now generates valid JSON Schema for collections whose JSON or YAML data is a top-level array.
HMR no longer serves stale content when components are passed as props through getStaticPaths().
Remote SVG sources pass through correctly without enabling dangerouslyProcessSVG or explicitly setting format="svg".
The dev server now serves fresh content after SSR-only modules change, including external monorepo files and dynamically imported components.
Actions and other SSR POST endpoints continue working in dev instead of returning HTTP 500 errors.
Fixes Hono cache middleware to follow the standard wrapper pattern.
Map and Set instances saved in a content collection are no longer broken when entries are retrieved.
Fixes entry.data type inference for live collections configured without a schema.
Styles are now extracted to head in the dev server for the specified Cloudflare prerender setup.
SVG images with width or height zero are treated as valid dimensions instead of throwing NoImageMetadata.
assetsPrefix is available on build from astro:config/server.
Compiler memory is correctly freed at the end of the build.
Astro.cache is always defined as a no-op shim when experimental.cache is not configured, allowing cache methods to be called without conditional checks.
Prevents HTMLElement is not defined errors during HMR for components with client-side scripts.
The dev image endpoint origin check is corrected.
Ampersands in meta tags no longer appear as raw entity strings in link previews or raw HTML.
Non-prerendered routes no longer fail when a dynamic prerendered route exists with prerenderEnvironment set to node.
Validation messages now better explain incorrect placement of script-src or style-src in the directives array.
Local images no longer return 404 on non-prerendered pages when using the generic image endpoint.
Hydration import failures now support retry and error event handling for transient network failures.
Locale selection now respects the first matching code in configured locales order.
Boolean arrays now correctly parse submitted "false" strings as false.
Deleted content collection entries no longer persist in development results.
CSP directives are no longer duplicated when inserted or merged.
SSR responses in astro dev no longer crash because logger.flush is unavailable.
Builds no longer crash when processing animated AVIF images.
Conditional named slot callbacks no longer receive unintended arguments.
Tap prefetching now triggers when clicking nested elements inside an anchor.
LiveLoader data types declared as interfaces are now accepted.
Dynamic parameters on non-page routes now preserve
.htmlvalues for endpoints and redirects.Dev rendering now propagates head metadata for adapters using the prerender Vite environment.
Fallback pages using rewrite mode now emit their page bodies during
astro build.The index route now resolves correctly with a custom base path and
trailingSlash: 'never'.Partial pages imported as components now contribute their CSS styles.
The
positionprop on Image and Picture components now correctly applies object-position styles.Script deduplication state is no longer consumed while rendering inert template contexts.
Deleting a session key as the first request mutation now persists correctly.
Astro component imports through tsconfig path aliases no longer cause style compilation failures.
Scoped styles now target the correct element with Lightning CSS and nested selectors inside
:where(...).Error formatting is now compatible with Zod 4.4.0.
Config validation now correctly handles omitted integrations fields with newer Zod versions.
Config validation no longer warns when the optional server property is missing.
The server config property is now compatible with Zod 4.4.0.
Scripts inside
<template>elements are no longer deduplicated.Stops a spurious content configuration warning for projects that do not use content collections.
Prevents a spurious dev toolbar sourcemap 404 caused by browser resolution from the
/@id/URL prefix.allowedDomains settings are correctly propagated when using the development server.
Build output filenames no longer contain special characters that can cause deployment failures on platforms like Netlify.
Build errors are fixed for inter-chunk JavaScript using dynamic imports on platforms with skew protection enabled.
Client-build asset hashes are no longer regenerated unnecessarily, making builds more stable.
Vue scoped style handling improves in development mode during client router navigation.
Remote image dimensions are now validated during static builds on Netlify.
Actions no longer fail with ActionsWithoutServerOutputError when output is static and an adapter is configured.
Inline script content now handles special characters more reliably.
SCSS and CSS module changes now hot-update styles in place during development instead of triggering a full page reload.
Sync content inside Fragment now streams without waiting for all async sibling expressions to resolve.
Fixes a build error when a pre-rendered page uses Picture and another page renders content collection entries.
Revives UnoCSS in dev mode when used with the client router.
Config changes in dev mode now restart Vite in place, preventing miniflare errors and 404 responses.
Pages with dots in their filenames no longer return 404 with trailing slashes in dev mode and respect the configured trailing slash behavior.
Static builds no longer produce redirect HTML instead of the actual response for extensionless endpoints when trailing slashes are always enabled.
Prevents HTML content from being incorrectly escaped as plain text when rendering MDX components through AstroContainer APIs.
Fixes dev rendering so head metadata is present and dev CSS/scripts are injected in the correct place.
Prevents page-level CSS from leaking between unrelated pages across top-level route boundaries.
Restores HMR when modifying files with the Cloudflare adapter and prerenderEnvironment set to 'node'.
Appends skew protection query parameters to inter-chunk JavaScript imports, preventing version mismatches during Vercel rolling deployments.
Allows SSR builds to succeed when projects contain only injected routes and no src/pages/ directory.
Catch-all routes no longer incorrectly intercept static asset requests with the @astrojs/node adapter in middleware mode.
Zod v4 validation errors now display human-readable messages instead of raw JSON.
astro preview now respects vite.preview.allowedHosts configured in astro.config.mjs.
Fixes Vue's :deep() notation being ignored by the client router in dev mode.
Prevents the dev toolbar audit from crashing when encountering the image ARIA role.
Automatically adds a Vite 7 override to package.json to prevent a require_dist crash caused by a Vite version split.
Prevents Rollup build failures when astro:config/client is used inside a script tag.
Allows cached assets to revalidate correctly when redirect checks encounter Not Modified responses.
Prevents duplicate client:component-path attributes from being added to client:only components in MDX.
Removes the unsupported emitFile warning during astro dev when integrations inject before-hydration scripts.
Stops queued rendering from escaping HTML page output so .html pages render as HTML instead of plain text.
Prevents font files from being copied several times unnecessarily during the build.
Prevents invalid development URLs for font families using an oblique style with angles.
Corrects the audit toolbar so the image role is not reported incorrectly.
Corrects the dev toolbar accessibility audit so menuitemradio is recognized as an interactive ARIA role.
Development server changes to middleware are now picked up without requiring a full restart.
Prevents an Astro Cloudflare dev server crash when navigating to a deferred server island after a page without one.
Correctly renders Zod metadata on the top-level schema when converting it to JSON Schema.
Nested object properties now work correctly, including with zod functions such as superRefine and discriminatedUnion.
The dev server no longer hangs on the first request when using the Cloudflare adapter.
Astro.currentLocale now resolves the actual locale for dynamic locale routes instead of always returning the default locale.
Styles from dynamically imported components are injected on the first dev server load.
URLs with locales that are not configured now render the custom 404 page instead of a dynamic locale page.
Static-page requests passed to Express or Fastify no longer leak socket listeners before next() is called.
Cloudflare dev server islands work with prerenderEnvironment set to node.
Images in markdown processed by custom content loaders are resolved and optimized correctly.
Server islands no longer fail at runtime in projects with multiple frontend integrations when all pages are prerendered.
HMR now correctly handles adding, changing, and deleting routes in
pages/on Windows.Type inference is fixed for content collections using a loader that includes a schema.
Client hydration now works for components imported through Node.js subpath imports, including Cloudflare adapter development.
Skew protection query parameters are applied to island hydration URLs and safely appended to asset URLs with existing search or hash parts.
SSR dynamic routes using an
.htmlextension now work correctly.Style-only changes now trigger eager recompilation to prevent stale slot rendering during HMR.
Validation now checks resolved routes, preventing startup failures with static output and at least one non-prerendered page or endpoint.
The shared Vite watcher listener limit is increased to avoid MaxListenersExceededWarning during development startup.
The root page pathname uses /index.html with build.format: "file" instead of /.html during builds.
The before-hydration script chunk is emitted for the client Vite environment, preventing 404s and restoring hydration for integrations using injectScript.
JSON schema generation now handles content collection schemas whose input and output shapes differ.
Custom prerenderers are always torn down during builds, including when getStaticPaths() throws.
Server island requests are treated as prerender-handler eligible, allowing deferred island content to load for node-prerendered pages.
Deferred islands no longer fail at runtime in prerendered pages for affected adapters, including Cloudflare.
The server entrypoint no longer leaks into the client environment, preventing adapter warnings during builds.
Prebundled in dev when custom toolbar apps are registered, preventing re-optimization reloads that can hide or break the toolbar.
Newly created pages in the dev server now receive layout-imported CSS without requiring a restart.
The dev server now serves a page when a project-root directory shares the page route's name.
Removes an incorrect warning when using prefetchAll.
Now produces an absolute path instead of a protocol-relative URL when base is '/'.
Server islands now work in prerendered pages when output is configured as server.
Unknown file extension errors now recommend the correct Vite 7 configuration key.
Routes emitted by the astro:build:done hook now have the distURL array correctly populated.
Prerendered routes now handle route and CSS updates, prerender middleware, route matching, and HMR consistently in Astro's dev environment.
Fixes return; syntax not working correctly in Astro frontmatter in certain contexts.
The tsconfig preview now shows the actual pending changes before confirmation.
Supports more operating systems when copying diagnostic information to the clipboard.
The astro:page-load event now fires on initial page loads.
Rewriting to URLs containing non-ASCII characters no longer incorrectly returns 404.
Framework components in multiple named MDX slots now receive their hydration scripts correctly.
build.serverEntry is respected when using the new Adapter API and works as expected again.
ClientRouter navigation preserves inline styles and font preload links, preventing font flashes caused by re-evaluated @font-face declarations.
ClientRouter preserves the target URL's original hash during server-side redirects.
Using the Code component no longer produces an unexpected error.
context.csp no longer logs warnings during development; those warnings are logged only in production.
The exported createApp types from astro/app/entrypoint are corrected.
CSP headers are no longer incorrectly injected by the development server.
Newly added pages are correctly shown and served while the development server is running.
Dynamic URL attribute values containing
&are now consistently escaped.poolSize can now be configured as 0.
Form actions from the original request are no longer executed while rendering error pages.
Rendering now preserves the hidden="until-found" attribute value.
Host header handling is improved for SSR deployments behind proxies.
Images now work in development when setups use port forwarding.
inferSize is no longer retained as an HTML attribute on emitted img elements for non-remote images.
Integration-injected scripts now load in the dev server with non-runnable environment adapters such as @astrojs/cloudflare.
JSON schema generation no longer fails for unrepresentable types.
The Picture component avoids creating unused images during builds.
Public files now take priority over generated API routes in both development and production builds.
Script tags from components passed as slots to server islands are now included in the response.
Regenerated session data is now saved under the new session ID without requiring an additional set() call.
Adding or removing style tags in Astro components now updates styles visually during development without restarting the server.
Setting vite.server.allowedHosts to true no longer produces an invalid array.
astro 5107 changes
Breaking changes 14
Remote image redirects are now rejected.
The experimental Fonts API no longer exports getFontBuffer due to significant memory usage during build.
Local fonts must now use the unified provider API with fontProviders.local() and move variants into options.
A fontData object replaces getFontData() for accessing font data by CSS variable and supports programmatic access to all font data.
Google and Google Icons family-specific options must now be configured on each font entry through the options property.
The experimental Fonts API no longer exports getFontData from astro:assets.
Changes the experimental FontProvider implementation and requires third-party unifont providers to wrap their runtime provider.
The experimental Fonts API removes defineAstroFontProvider(); custom font providers should use the FontProvider type instead.
Using output: "hybrid" now produces a helpful error explaining the option was removed and recommending output: "static".
The experimental Fonts API now defaults to only the latin subset; extra subsets must be selected manually.
Data URIs now require explicit authorization through a remote pattern configuration.
The passthrough image service no longer generates WebP output.
Malformed cookies now return the raw unparsed value instead of throwing a URIError.
Live loader cacheHint objects no longer support maxAge; set page max age through headers instead.
Security 14
Astro: Remote allowlist bypass via unanchored matchPathname wildcard
Fixes protocol validation when allowedDomains includes both protocol and hostname fields.
Image allowlists are now respected when remote image sizes are inferred.
Certain unauthorized links are no longer rendered as clickable in the error overlay.
Server island requests now carry an encrypted component export identifier to prevent resolving to the wrong component.
CSP resources from configuration and the runtime API are combined into grammatically correct, deduplicated CSP headers.
Middleware validates decoded pathnames to prevent authentication bypass through multi-level URL encoding.
Astro Cloudflare adapter has Stored Cross-site Scripting vulnerability in /_image endpoint
Astro vulnerable to reflected XSS via the server islands feature
Middleware receives normalized, decoded pathname values so URL-encoded paths cannot bypass checks.
Slots are encrypted before browser transmission, improving integrity and preventing injection attacks.
Astro development server error page is vulnerable to reflected Cross-site Scripting
Validates forwarded headers against allowedDomains patterns to prevent cache poisoning and header injection attacks.
Fixes a leak of server runtime code into client bundles when importing SVG files in client-side code.
Deprecations 1
Astro.glob is now correctly marked as deprecated.
New APIs and options 21
Cookies can be created as partitioned cookies with partitioned: true; they must also use secure: true.
The dev toolbar position can be configured as bottom-left, bottom-center, or bottom-right.
The glob() loader can omit raw content bodies from the data store to reduce deployed data-store size.
The Image component and getImage() helper can flatten transparent images using a specified background color.
Sharp image resizing can use a configured kernel instead of the default lanczos3 algorithm.
Custom FontProvider init() contexts now expose a root URL for resolving local files.
Adds a helper to retrieve font file buffers from URLs returned by getFontData(), including during prerendering.
Experimental font providers can declare family-specific options through a generic, with options inferred in Astro configuration.
Adds Google Icons as a built-in font provider available through fontProviders.
The experimental Fonts API adds formats to specify which font formats to download.
Supports extending the type of props accepted by the getImage API.
Supports extending the type of props accepted by Astro’s Image component.
Supports extending the type of props accepted by Astro’s Picture component.
Button attribute types now allow command.
Button attribute types now allow commandfor.
Adds a utility type that infers an action's TypeScript input type from its Zod schema.
Adds experimental SVGO optimization for SVG assets during builds, reducing file sizes while maintaining visual quality.
Adds an export alias for astro/jsx-runtime, enabling JSX development runtime imports through astro/jsx-dev-runtime.
Adapters can append query parameters to all generated asset URLs during the build process.
Adapters can provide headers for Astro internal fetch calls, including Actions, View Transitions, Server Islands, and Prefetch.
The experimental Fonts API can preload selected font weights, styles, or subsets for a font family.
Performance 2
Render chunks are grouped when emitted from async iterables to avoid encoding costs, improving rendering performance.
Build performance and memory usage improve for medium-sized blogs with many content entries.
Behavior and default changes 6
The file() loader parser() option can now return a Promise, enabling asynchronous fetching and parsing.
The glob() loader now warns when duplicated IDs are detected.
The experimental Fonts API warns when provided font families use conflicting cssVariable values.
Remote font families can be specified multiple times with different weight and style combinations, downloading only the required files.
getContainerRenderer() now returns a client hydration entrypoint, enabling client-side interactivity without manually calling container.addClientRenderer().
Adapter-level query parameters now apply to all image and font asset URLs, including dynamic and static optimized images and experimental Fonts API requests.
Tooling 6
Adding the Vercel adapter now adds .vercel to .gitignore.
Adds keyboard shortcuts to open the site, quit the preview, and display available shortcuts.
The experimental Fonts API build log now shows the number of downloaded files, helping identify excessive downloading from misconfiguration.
The command now scaffolds wrangler.jsonc and public/.assetsignore so Astro projects work out of the box as workers.
The MDX Content component's components prop now has TypeScript support when using await render(), providing IntelliSense and type checking.
The dev-mode error overlay stack trace now has a button for copying the stack trace.
Fixes and other changes 43
SSR manifests now populate styles for prerendered routes, allowing workers or middleware to discover the CSS files used by a prerendered page.
Font providers supplied as class instances now work with the experimental Fonts API, including the local provider.
CSS assets with remote assetsPrefix URLs no longer receive an invalid leading slash in generated stylesheet links.
CSS deduplication is reintroduced for hydrated client components, preventing assets in client chunks from being flagged as orphaned.
Stopping the dev server with q+enter no longer creates a dist folder or copies font files.
React components nested inside HTML elements in MDX files now hydrate correctly.
Styles for conditionally rendered Svelte 5 components are now included in production builds.
Prevents the same CSS file from being bundled twice when imported in page frontmatter and a component script.
Validates route modules and provides a descriptive error when a valid page function is missing.
Fixes CSS url() references to public assets returning 404 in dev mode when a base path is configured.
Fixes an image 500 error when moving the dist directory in standalone Node deployments.
Fixes component scripts failing to render when an unused sibling slot Fragment exists.
Requests with query parameters to the base path no longer return a 404 in development when trailingSlash is not ignore.
Cookie values set with context.cookies.set() are no longer overridden by cookies set through response headers in development.
The Unsupported page types found error now appears only in more realistic cases.
The audit warning is skipped for images inside framework components such as React, Vue, and Svelte.
Certain aliases now work when using images in JSON files with the content layer.
Remote image Etag header handling is fixed by disabling the internal cache.
Images outside the project directory now work with astro:assets in development mode.
SVGs now work in development mode when using the passthrough image service.
JSDoc annotations now appear for font-related APIs in the Astro config.
Actions types now work correctly with specific TypeScript configurations.
In SSR, setting a page status to 404 now uses the current page instead of showing an empty page or 404.astro.
A Vite warning log during builds when using npm is fixed.
Restores support for Astro component rendering in Vitest suites using client environments such as happy-dom or jsdom.
Fixes an unhandled rejection issue when using Astro with Vercel Workflow DevKit.
Wildcard hostname matching now rejects single-part hostnames that do not contain valid matching subdomains.
Adds handling for invalid encrypted props and slots in server islands.
The rewrite fallback system now generates fallback files for pages whose filename starts with a locale key.
process.env is now properly populated during the build.
Hydration now works in the dev server when a barrel file re-exports Astro and UI framework components.
Persisted components using declarative Shadow DOM no longer fail navigation because Astro avoids re-attaching an existing shadow root.
Improves fallback generation when using the experimental Fonts API.
Prevents build-time process.env values from being incorrectly inlined into server output.
The experimental Fonts API no longer filters available font files too aggressively, allowing Google-provider woff files to download.
Fixes a regression that caused ?url imports to not work correctly.
Normalizes bare filenames to relative paths for consistent image resolution in markdown frontmatter and JSON content collections.
The actions endpoint returns 404 for non-existent actions instead of throwing an unhandled error.
Actions no longer throw errors while loading.
Astro.site is no longer always undefined inside getStaticPaths().
CSS handling for hydrated client components now prevents duplicate styles.
The muted HTML attribute now behaves consistently with other attributes.
The experimental live collections entry type now includes rendered, preventing TypeScript errors when using it.