withastro/astro (astro)
Compare Source
Patch Changes
Compare Source
Patch Changes
Compare Source
Minor Changes
-
#14173 39911b8 Thanks @florian-lefebvre! - Adds an experimental flag staticImportMetaEnv to disable the replacement of import.meta.env values with process.env calls and their coercion of environment variable values. This supersedes the rawEnvValues experimental flag, which is now removed.
Astro allows you to configure a type-safe schema for your environment variables, and converts variables imported via astro:env into the expected type. This is the recommended way to use environment variables in Astro, as it allows you to easily see and manage whether your variables are public or secret, available on the client or only on the server at build time, and the data type of your values.
However, you can still access environment variables through process.env and import.meta.env directly when needed. This was the only way to use environment variables in Astro before astro:env was added in Astro 5.0, and Astro's default handling of import.meta.env includes some logic that was only needed for earlier versions of Astro.
The experimental.staticImportMetaEnv flag updates the behavior of import.meta.env to align with Vite's handling of environment variables and for better ease of use with Astro's current implementations and features. This will become the default behavior in Astro 6.0, and this early preview is introduced as an experimental feature.
Currently, non-public import.meta.env environment variables are replaced by a reference to process.env. Additionally, Astro may also convert the value type of your environment variables used through import.meta.env, which can prevent access to some values such as the strings "true" (which is converted to a boolean value), and "1" (which is converted to a number).
The experimental.staticImportMetaEnv flag simplifies Astro's default behavior, making it easier to understand and use. Astro will no longer replace any import.meta.env environment variables with a process.env call, nor will it coerce values.
To enable this feature, add the experimental flag in your Astro config and remove rawEnvValues if it was enabled:
// astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
+ experimental: {
+ staticImportMetaEnv: true
- rawEnvValues: false
+ }
});
Updating your project
If you were relying on Astro's default coercion, you may need to update your project code to apply it manually:
// src/components/MyComponent.astro
- const enabled: boolean = import.meta.env.ENABLED;
+ const enabled: boolean = import.meta.env.ENABLED === "true";
If you were relying on the transformation into process.env calls, you may need to update your project code to apply it manually:
// src/components/MyComponent.astro
- const enabled: boolean = import.meta.env.DB_PASSWORD;
+ const enabled: boolean = process.env.DB_PASSWORD;
You may also need to update types:
// src/env.d.ts
interface ImportMetaEnv {
readonly PUBLIC_POKEAPI: string;
- readonly DB_PASSWORD: string;
- readonly ENABLED: boolean;
+ readonly ENABLED: string;
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}
+ namespace NodeJS {
+ interface ProcessEnv {
+ DB_PASSWORD: string;
+ }
+ }See the experimental static import.meta.env documentation for more information about this feature. You can learn more about using environment variables in Astro, including astro:env, in the environment variables documentation.
-
#14122 41ed3ac Thanks @ascorbic! - Adds experimental support for automatic Chrome DevTools workspace folders
This feature allows you to edit files directly in the browser and have those changes reflected in your local file system via a connected workspace folder. This allows you to apply edits such as CSS tweaks without leaving your browser tab!
With this feature enabled, the Astro dev server will automatically configure a Chrome DevTools workspace for your project. Your project will then appear as a workspace source, ready to connect. Then, changes that you make in the "Sources" panel are automatically saved to your project source code.
To enable this feature, add the experimental flag chromeDevtoolsWorkspace to your Astro config:
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
chromeDevtoolsWorkspace: true,
},
});See the experimental Chrome DevTools workspace feature documentation for more information.
Compare Source
Patch Changes
-
#14020 9518975 Thanks @jp-knj and @asieradzk! - Prevent double-prefixed redirect paths when using fallback and redirectToDefaultLocale together
Fixes an issue where i18n fallback routes would generate double-prefixed paths (e.g., /es/es/test/item1/) when fallback and redirectToDefaultLocale configurations were used together. The fix adds proper checks to prevent double prefixing in route generation.
-
#14199 3e4cb8e Thanks @ascorbic! - Fixes a bug that prevented HMR from working with inline styles
Compare Source
Patch Changes
Compare Source
Patch Changes
-
#14169 f4e8889 Thanks @ascorbic! - Skips trailing slash handling for paths that start with /..
-
#14170 34e6b3a Thanks @ematipico! - Fixes an issue where static redirects couldn't correctly generate a redirect when the destination is a prerendered route, and the output is set to "server".
-
#14169 f4e8889 Thanks @ascorbic! - Fixes a bug that prevented images from being displayed in dev when using the Netlify adapter with trailingSlash set to always
-
Updated dependencies [f4e8889]:
Compare Source
Patch Changes
-
#14153 29e9283 Thanks @jp-knj! - Fixes a regression introduced by a recent optimisation of how SVG images are emitted during the build.
-
#14156 592f08d Thanks @TheOtterlord! - Fix the client router not submitting forms if the active URL contained a hash
-
#14160 d2e25c6 Thanks @ascorbic! - Fixes a bug that meant some remote image URLs could cause invalid filenames to be used for processed images
-
#14167 62bd071 Thanks @ascorbic! - Fixes a bug that prevented destroyed sessions from being deleted from storage unless the session had been loaded
Compare Source
Patch Changes
-
#14059 19f53eb Thanks @benosmac! - Fixes a bug in i18n implementation, where Astro didn't emit the correct pages when fallback is enabled, and a locale uses a catch-all route, e.g. src/pages/es/[...catchAll].astro
-
#14155 31822c3 Thanks @ascorbic! - Fixes a bug that caused an error "serverEntrypointModule[_start] is not a function" in some adapters
Compare Source
Patch Changes
Compare Source
Patch Changes
-
#14119 14807a4 Thanks @ascorbic! - Fixes a bug that caused builds to fail if a client directive was mistakenly added to an Astro component
-
#14001 4b03d9c Thanks @dnek! - Fixes an issue where getImage() assigned the resized base URL to the srcset URL of ImageTransform, which matched the width, height, and format of the original image.
Compare Source
Patch Changes
Compare Source
Patch Changes
Compare Source
Minor Changes
-
#13971 fe35ee2 Thanks @adamhl8! - Adds an experimental flag rawEnvValues to disable coercion of import.meta.env values (e.g. converting strings to other data types) that are populated from process.env
Astro allows you to configure a type-safe schema for your environment variables, and converts variables imported via astro:env into the expected type.
However, Astro also converts your environment variables used through import.meta.env in some cases, and this can prevent access to some values such as the strings "true" (which is converted to a boolean value), and "1" (which is converted to a number).
The experimental.rawEnvValues flag disables coercion of import.meta.env values that are populated from process.env, allowing you to use the raw value.
To enable this feature, add the experimental flag in your Astro config:
import { defineConfig } from "astro/config"
export default defineConfig({
+ experimental: {
+ rawEnvValues: true,
+ }
})If you were relying on this coercion, you may need to update your project code to apply it manually:
- const enabled: boolean = import.meta.env.ENABLED
+ const enabled: boolean = import.meta.env.ENABLED === "true"
See the experimental raw environment variables reference docs for more information.
-
#13941 6bd5f75 Thanks @aditsachde! - Adds support for TOML files to Astro's built-in glob() and file() content loaders.
In Astro 5.2, Astro added support for using TOML frontmatter in Markdown files instead of YAML. However, if you wanted to use TOML files as local content collection entries themselves, you needed to write your own loader.
Astro 5.12 now directly supports loading data from TOML files in content collections in both the glob() and the file() loaders.
If you had added your own TOML content parser for the file() loader, you can now remove it as this functionality is now included:
// src/content.config.ts
import { defineCollection } from "astro:content";
import { file } from "astro/loaders";
- import { parse as parseToml } from "toml";
const dogs = defineCollection({
- loader: file("src/data/dogs.toml", { parser: (text) => parseToml(text) }),
+ loader: file("src/data/dogs.toml")
schema: /* ... */
})Note that TOML does not support top-level arrays. Instead, the file() loader considers each top-level table to be an independent entry. The table header is populated in the id field of the entry object.
See Astro's content collections guide for more information on using the built-in content loaders.
Patch Changes
Compare Source
Patch Changes
-
#14064 2eb77d8 Thanks @jp-knj! - Allows using tsconfig compilerOptions.paths without setting compilerOptions.baseUrl
-
#14068 10189c0 Thanks @jsparkdev! - Fixes the incorrect CSS import path shown in the terminal message during Tailwind integration setup.
Compare Source
Patch Changes
-
#14045 3276b79 Thanks @ghubo! - Fixes a problem where importing animated .avif files returns a NoImageMetadata error.
-
#14041 0c4d5f8 Thanks @dixslyf! - Fixes a <ClientRouter /> bug where the fallback view transition animations when exiting a page
ran too early for browsers that do not support the View Transition API.
This bug prevented event.viewTransition?.skipTransition() from skipping the page exit animation
when used in an astro:before-swap event hook.
Compare Source
Minor Changes
-
#13972 db8f8be Thanks @ematipico! - Updates the NodeApp.match() function in the Adapter API to accept a second, optional parameter to allow adapter authors to add headers to static, prerendered pages.
NodeApp.match(request) currently checks whether there is a route that matches the given Request. If there is a prerendered route, the function returns undefined, because static routes are already rendered and their headers cannot be updated.
When the new, optional boolean parameter is passed (e.g. NodeApp.match(request, true)), Astro will return the first matched route, even when it's a prerendered route. This allows your adapter to now access static routes and provides the opportunity to set headers for these pages, for example, to implement a Content Security Policy (CSP).
Patch Changes
Compare Source
Patch Changes
-
#14000 3cbedae Thanks @feelixe! - Fix routePattern JSDoc examples to show correct return values
-
#13990 de6cfd6 Thanks @isVivek99! - Fixes a case where astro:config/client and astro:config/server virtual modules would not contain config passed to integrations updateConfig() during the build
-
#14019 a160d1e Thanks @ascorbic! - Removes the requirement to set type: 'live' when defining experimental live content collections
Previously, live collections required a type and loader configured. Now, Astro can determine that your collection is a live collection without defining it explicitly.
This means it is now safe to remove type: 'live' from your collections defined in src/live.config.ts:
import { defineLiveCollection } from 'astro:content';
import { storeLoader } from '@​mystore/astro-loader';
const products = defineLiveCollection({
- type: 'live',
loader: storeLoader({
apiKey: process.env.STORE_API_KEY,
endpoint: 'https://api.mystore.com/v1',
}),
});
export const collections = { products };This is not a breaking change: your existing live collections will continue to work even if you still include type: 'live'. However, we suggest removing this line at your earliest convenience for future compatibility when the feature becomes stable and this config option may be removed entirely.
-
#13966 598da21 Thanks @msamoylov! - Fixes a broken link on the default 404 page in development
Compare Source
Patch Changes
-
#13988 609044c Thanks @ascorbic! - Fixes a bug in live collections that caused it to incorrectly complain about the collection being defined in the wrong file
-
#13909 b258d86 Thanks @isVivek99! - Fixes rendering of special boolean attributes for custom elements
-
#13983 e718375 Thanks @florian-lefebvre! - Fixes a case where the toolbar audit would incorrectly flag images processed by Astro in content collections documents
-
#13999 f077b68 Thanks @ascorbic! - Adds lastModified field to experimental live collection cache hints
Live loaders can now set a lastModified field in the cache hints for entries and collections to indicate when the data was last modified. This is then available in the cacheHint field returned by getCollection and getEntry.
-
#13987 08f34b1 Thanks @ematipico! - Adds an informative message in dev mode when the CSP feature is enabled.
-
#14005 82aad62 Thanks @ematipico! - Fixes a bug where inline styles and scripts didn't work when CSP was enabled. Now when adding <styles> elements inside an Astro component, their hashes care correctly computed.
-
#13985 0b4c641 Thanks @jsparkdev! - Updates wrong link
Compare Source
Minor Changes
-
#13917 e615216 Thanks @ascorbic! - Adds a new priority attribute for Astro's image components.
This change introduces a new priority option for the <Image /> and <Picture /> components, which automatically sets the loading, decoding, and fetchpriority attributes to their optimal values for above-the-fold images which should be loaded immediately.
It is a boolean prop, and you can use the shorthand syntax by simply adding priority as a prop to the <Image /> or <Picture /> component. When set, it will apply the following attributes:
loading="eager"decoding="sync"fetchpriority="high"
The individual attributes can still be set manually if you need to customize your images further.
By default, the Astro <Image /> component generates <img> tags that lazy-load their content by setting loading="lazy" and decoding="async". This improves performance by deferring the loading of images that are not immediately visible in the viewport, and gives the best scores in performance audits like Lighthouse.
The new priority attribute will override those defaults and automatically add the best settings for your high-priority assets.
This option was previously available for experimental responsive images, but now it is a standard feature for all images.
Usage
<Image src="/path/to/image.jpg" alt="An example image" priority />
[!Note]
You should only use the priority option for images that are critical to the initial rendering of the page, and ideally only one image per page. This is often an image identified as the LCP element when running Lighthouse tests. Using it for too many images will lead to performance issues, as it forces the browser to load those images immediately, potentially blocking the rendering of other content.
-
#13917 e615216 Thanks @ascorbic! - The responsive images feature introduced behind a flag in v5.0.0 is no longer experimental and is available for general use.
The new responsive images feature in Astro automatically generates optimized images for different screen sizes and resolutions, and applies the correct attributes to ensure that images are displayed correctly on all devices.
Enable the image.responsiveStyles option in your Astro config. Then, set a layout attribute on any or component, or configure a default image.layout, for instantly responsive images with automatically generated srcset and sizes attributes based on the image's dimensions and the layout type.
Displaying images correctly on the web can be challenging, and is one of the most common performance issues seen in sites. This new feature simplifies the most challenging part of the process: serving your site visitor an image optimized for their viewing experience, and for your website's performance.
For full details, see the updated Image guide.
Migration from Experimental Responsive Images
The experimental.responsiveImages flag has been removed, and all experimental image configuration options have been renamed to their final names.
If you were using the experimental responsive images feature, you'll need to update your configuration:
Remove the experimental flag
export default defineConfig({
experimental: {
- responsiveImages: true,
},
});Update image configuration options
During the experimental phase, default styles were applied automatically to responsive images. Now, you need to explicitly set the responsiveStyles option to true if you want these styles applied.
export default defineConfig({
image: {
+ responsiveStyles: true,
},
});The experimental image configuration options have been renamed:
Before:
export default defineConfig({
image: {
experimentalLayout: 'constrained',
experimentalObjectFit: 'cover',
experimentalObjectPosition: 'center',
experimentalBreakpoints: [640, 750, 828, 1080, 1280],
experimentalDefaultStyles: true,
},
experimental: {
responsiveImages: true,
},
});After:
export default defineConfig({
image: {
layout: 'constrained',
objectFit: 'cover',
objectPosition: 'center',
breakpoints: [640, 750, 828, 1080, 1280],
responsiveStyles: true, // This is now *false* by default
},
});Component usage remains the same
The layout, fit, and position props on <Image> and <Picture> components work exactly the same as before:
<Image
src={myImage}
alt="A responsive image"
layout="constrained"
fit="cover"
position="center"
/>If you weren't using the experimental responsive images feature, no changes are required.
Please see the Image guide for more information on using responsive images in Astro.
-
#13685 3c04c1f Thanks @ascorbic! - Adds experimental support for live content collections
Live content collections are a new type of content collection that fetch their data at runtime rather than build time. This allows you to access frequently-updated data from CMSs, APIs, databases, or other sources using a unified API, without needing to rebuild your site when the data changes.
Live collections vs build-time collections
In Astro 5.0, the content layer API added support for adding diverse content sources to content collections. You can create loaders that fetch data from any source at build time, and then access it inside a page via getEntry() and getCollection(). The data is cached between builds, giving fast access and updates.
However there is no method for updating the data store between builds, meaning any updates to the data need a full site deploy, even if the pages are rendered on-demand. This means that content collections are not suitable for pages that update frequently. Instead, today these pages tend to access the APIs directly in the frontmatter. This works, but leads to a lot of boilerplate, and means users don't benefit from the simple, unified API that content loaders offer. In most cases users tend to individually create loader libraries that they share between pages.
Live content collections solve this problem by allowing you to create loaders that fetch data at runtime, rather than build time. This means that the data is always up-to-date, without needing to rebuild the site.
How to use
To enable live collections add the experimental.liveContentCollections flag to your astro.config.mjs file:
{
experimental: {
liveContentCollections: true,
},
}Then create a new src/live.config.ts file (alongside your src/content.config.ts if you have one) to define your live collections with a live loader and optionally a schema using the new defineLiveCollection() function from the astro:content module.
import { defineLiveCollection } from 'astro:content';
import { storeLoader } from '@​mystore/astro-loader';
const products = defineLiveCollection({
type: 'live',
loader: storeLoader({
apiKey: process.env.STORE_API_KEY,
endpoint: 'https://api.mystore.com/v1',
}),
});
export const collections = { products };You can then use the dedicated getLiveCollection() and getLiveEntry() functions to access your live data:
Compare Source
Patch Changes
Compare Source
Patch Changes
-
#13923 a9ac5ed Thanks @ematipico! - BREAKING CHANGE to the experimental Content Security Policy (CSP) only
Changes the behavior of experimental Content Security Policy (CSP) to now serve hashes differently depending on whether or not a page is prerendered:
- Via the
<meta> element for static pages.
- Via the
Response header content-security-policy for on-demand rendered pages.
This new strategy allows you to add CSP content that is not supported in a <meta> element (e.g. report-uri, frame-ancestors, and sandbox directives) to on-demand rendered pages.
No change to your project code is required as this is an implementation detail. However, this will result in a different HTML output for pages that are rendered on demand. Please check your production site to verify that CSP is working as intended.
To keep up to date with this developing feature, or to leave feedback, visit the CSP Roadmap proposal.
-
#13926 953a249 Thanks @ematipico! - Adds a new Astro Adapter Feature called experimentalStaticHeaders to allow your adapter to receive the Headers for rendered static pages.
Adapters that enable support for this feature can access header values directly, affecting their handling of some Astro features such as Content Security Policy (CSP). For example, Astro will no longer serve the CSP <meta http-equiv="content-security-policy"> element in static pages to adapters with this support.
Astro will serve the value of the header inside a map that can be retrieved from the hook astro:build:generated. Adapters can read this mapping and use their hosting headers capabilities to create a configuration file.
A new field called experimentalRouteToHeaders will contain a map of Map<IntegrationResolvedRoute, Headers> where the Headers type contains the headers emitted by the rendered static route.
To enable support for this experimental Astro Adapter Feature, add it to your adapterFeatures in your adapter config:
// my-adapter.mjs
export default function createIntegration() {
return {
name: '@​example/my-adapter',
hooks: {
'astro:config:done': ({ setAdapter }) => {
setAdapter({
name: '@​example/my-adapter',
serverEntrypoint: '@​example/my-adapter/server.js',
adapterFeatures: {
experimentalStaticHeaders: true,
},
});
},
},
};
}See the Adapter API docs for more information about providing adapter features.
-
#13697 af83b85 Thanks @benosmac! - Fixes issues with fallback route pattern matching when i18n.routing.fallbackType is rewrite.
- Adds conditions for route matching in
generatePath when building fallback routes and checking for existing translated pages
Now for a route to be matched it needs to be inside a named [locale] folder. This fixes an issue where route.pattern.test() incorrectly matched dynamic routes, causing the page to be skipped.
- Adds conditions for route matching in
findRouteToRewrite
Now the requested pathname must exist in route.distURL for a dynamic route to match. This fixes an issue where route.pattern.test() incorrectly matched dynamic routes, causing the build to fail.
-
#13924 1cd8c3b Thanks @qw-in! - Fixes an edge case where isPrerendered was incorrectly set to false for static redirects.
-
#13926 953a249 Thanks @ematipico! - Fixes an issue where the experimental CSP meta element wasn't placed in the <head> element as early as possible, causing these policies to not apply to styles and scripts that came before the meta element.
Compare Source
Patch Changes
-
#13919 423fe60 Thanks @ematipico! - Fixes a bug where Astro added quotes to the CSP resources.
Only certain resources require quotes (e.g. 'self' but not https://cdn.example.com), so Astro no longer adds quotes to any resources. You must now provide the quotes yourself for resources such as 'self' when necessary:
export default defineConfig({
experimental: {
csp: {
styleDirective: {
resources: [
- "self",
+ "'self'",
"https://cdn.example.com"
]
}
}
}
})
-
#13914 76c5480 Thanks @ematipico! - BREAKING CHANGE to the experimental Content Security Policy feature only
Removes support for experimental Content Security Policy (CSP) when using the <ClientRouter /> component for view transitions.
It is no longer possible to enable experimental CSP while using Astro's view transitions. Support was already unstable with the <ClientRouter /> because CSP required making its underlying implementation asynchronous. This caused breaking changes for several users and therefore, this PR removes support completely.
If you are currently using the component for view transitions, please remove the experimental CSP flag as they cannot be used together.
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
- csp: true
}
});Alternatively, to continue using experimental CSP in your project, you can consider migrating to the browser native View Transition API and remove the <ClientRouter /> from your project. You may be able to achieve similar results if you are not using Astro's enhancements to the native View Transitions and Navigation APIs.
Support might be reintroduced in future releases. You can follow this experimental feature's development in the CSP RFC.
Compare Source
Patch Changes
Compare Source
Minor Changes
-
#13802 0eafe14 Thanks @ematipico! - Adds experimental Content Security Policy (CSP) support
CSP is an important feature to provide fine-grained control over resources that can or cannot be downloaded and executed by a document. In particular, it can help protect against cross-site scripting (XSS) attacks.
Enabling this feature adds additional security to Astro's handling of processed and bundled scripts and styles by default, and allows you to further configure these, and additional, content types. This new experimental feature has been designed to work in every Astro rendering environment (static pages, dynamic pages and single page applications), while giving you maximum flexibility and with type-safety in mind.
It is compatible with most of Astro's features such as client islands, and server islands, although Astro's view transitions using the <ClientRouter /> are not yet fully supported. Inline scripts are not supported out of the box, but you can provide your own hashes for external and inline scripts.
To enable this feature, add the experimental flag in your Astro config:
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
csp: true,
},
});For more information on enabling and using this feature in your project, see the Experimental CSP docs.
For a complete overview, and to give feedback on this experimental API, see the Content Security Policy RFC.
-
#13850 1766d22 Thanks [@ascorbic](https://redire
Uh oh!
There was an error while loading. Please reload this page.
This PR contains the following updates:
^4.3.5->^5.0.0Release Notes
withastro/astro (astro)
v5.13.2Compare Source
Patch Changes
4d16de7Thanks @ematipico! - Improves the detection of remote paths in the_imageendpoint. Nowhrefparameters that start with//are considered remote paths.Updated dependencies [
4d16de7]:v5.13.1Compare Source
Patch Changes
f2490abThanks @delucis! - Fixes theexperimental.chromeDevtoolsWorkspacefeature.v5.13.0Compare Source
Minor Changes
#14173
39911b8Thanks @florian-lefebvre! - Adds an experimental flagstaticImportMetaEnvto disable the replacement ofimport.meta.envvalues withprocess.envcalls and their coercion of environment variable values. This supersedes therawEnvValuesexperimental flag, which is now removed.Astro allows you to configure a type-safe schema for your environment variables, and converts variables imported via
astro:envinto the expected type. This is the recommended way to use environment variables in Astro, as it allows you to easily see and manage whether your variables are public or secret, available on the client or only on the server at build time, and the data type of your values.However, you can still access environment variables through
process.envandimport.meta.envdirectly when needed. This was the only way to use environment variables in Astro beforeastro:envwas added in Astro 5.0, and Astro's default handling ofimport.meta.envincludes some logic that was only needed for earlier versions of Astro.The
experimental.staticImportMetaEnvflag updates the behavior ofimport.meta.envto align with Vite's handling of environment variables and for better ease of use with Astro's current implementations and features. This will become the default behavior in Astro 6.0, and this early preview is introduced as an experimental feature.Currently, non-public
import.meta.envenvironment variables are replaced by a reference toprocess.env. Additionally, Astro may also convert the value type of your environment variables used throughimport.meta.env, which can prevent access to some values such as the strings"true"(which is converted to a boolean value), and"1"(which is converted to a number).The
experimental.staticImportMetaEnvflag simplifies Astro's default behavior, making it easier to understand and use. Astro will no longer replace anyimport.meta.envenvironment variables with aprocess.envcall, nor will it coerce values.To enable this feature, add the experimental flag in your Astro config and remove
rawEnvValuesif it was enabled:// astro.config.mjs import { defineConfig } from "astro/config"; export default defineConfig({ + experimental: { + staticImportMetaEnv: true - rawEnvValues: false + } });Updating your project
If you were relying on Astro's default coercion, you may need to update your project code to apply it manually:
If you were relying on the transformation into
process.envcalls, you may need to update your project code to apply it manually:You may also need to update types:
// src/env.d.ts interface ImportMetaEnv { readonly PUBLIC_POKEAPI: string; - readonly DB_PASSWORD: string; - readonly ENABLED: boolean; + readonly ENABLED: string; } interface ImportMeta { readonly env: ImportMetaEnv; } + namespace NodeJS { + interface ProcessEnv { + DB_PASSWORD: string; + } + }See the experimental static
import.meta.envdocumentation for more information about this feature. You can learn more about using environment variables in Astro, includingastro:env, in the environment variables documentation.#14122
41ed3acThanks @ascorbic! - Adds experimental support for automatic Chrome DevTools workspace foldersThis feature allows you to edit files directly in the browser and have those changes reflected in your local file system via a connected workspace folder. This allows you to apply edits such as CSS tweaks without leaving your browser tab!
With this feature enabled, the Astro dev server will automatically configure a Chrome DevTools workspace for your project. Your project will then appear as a workspace source, ready to connect. Then, changes that you make in the "Sources" panel are automatically saved to your project source code.
To enable this feature, add the experimental flag
chromeDevtoolsWorkspaceto your Astro config:See the experimental Chrome DevTools workspace feature documentation for more information.
v5.12.9Compare Source
Patch Changes
#14020
9518975Thanks @jp-knj and @asieradzk! - Prevent double-prefixed redirect paths when using fallback and redirectToDefaultLocale togetherFixes an issue where i18n fallback routes would generate double-prefixed paths (e.g.,
/es/es/test/item1/) whenfallbackandredirectToDefaultLocaleconfigurations were used together. The fix adds proper checks to prevent double prefixing in route generation.#14199
3e4cb8eThanks @ascorbic! - Fixes a bug that prevented HMR from working with inline stylesv5.12.8Compare Source
Patch Changes
0567fb7Thanks @ascorbic! - Adds//to list of internal path prefixes that do not have automated trailing slash handling#13894
b36e72fThanks @florian-lefebvre! - Removes Astro Studio commands from the CLI helpUpdated dependencies [
0567fb7]:v5.12.7Compare Source
Patch Changes
#14169
f4e8889Thanks @ascorbic! - Skips trailing slash handling for paths that start with/..#14170
34e6b3aThanks @ematipico! - Fixes an issue where static redirects couldn't correctly generate a redirect when the destination is a prerendered route, and theoutputis set to"server".#14169
f4e8889Thanks @ascorbic! - Fixes a bug that prevented images from being displayed in dev when using the Netlify adapter withtrailingSlashset toalwaysUpdated dependencies [
f4e8889]:v5.12.6Compare Source
Patch Changes
#14153
29e9283Thanks @jp-knj! - Fixes a regression introduced by a recent optimisation of how SVG images are emitted during the build.#14156
592f08dThanks @TheOtterlord! - Fix the client router not submitting forms if the active URL contained a hash#14160
d2e25c6Thanks @ascorbic! - Fixes a bug that meant some remote image URLs could cause invalid filenames to be used for processed images#14167
62bd071Thanks @ascorbic! - Fixes a bug that prevented destroyed sessions from being deleted from storage unless the session had been loadedv5.12.5Compare Source
Patch Changes
#14059
19f53ebThanks @benosmac! - Fixes a bug in i18n implementation, where Astro didn't emit the correct pages whenfallbackis enabled, and a locale uses a catch-all route, e.g.src/pages/es/[...catchAll].astro#14155
31822c3Thanks @ascorbic! - Fixes a bug that caused an error "serverEntrypointModule[_start] is not a function" in some adaptersv5.12.4Compare Source
Patch Changes
#14031
e9206c1Thanks @jp-knj! - Optimized the build pipeline for SVG images. Now, Astro doesn't reprocess images that have already been processed.#14132
976879aThanks @ematipico! - Fixes a bug where the propertyAstro.routePattern/context.routePatternwasn't updated when using a rewrite via middleware.#14131
aafc4d7Thanks @florian-lefebvre! - Fixes a case where an error occurring in a middleware would show the dev overlay instead of the custom500.astropage#14127
2309adaThanks @florian-lefebvre! - Upgrades zod#14134
186c201Thanks @ascorbic! - Throws a more helpful error in dev if trying to use a server island without an adapter#14129
3572d85Thanks @ematipico! - Fixes a bug where the CSP headers was incorrectly added to a page when using an adapter.v5.12.3Compare Source
Patch Changes
#14119
14807a4Thanks @ascorbic! - Fixes a bug that caused builds to fail if a client directive was mistakenly added to an Astro component#14001
4b03d9cThanks @dnek! - Fixes an issue wheregetImage()assigned the resized base URL to the srcset URL ofImageTransform, which matched the width, height, and format of the original image.v5.12.2Compare Source
Patch Changes
#14071
d2cb35dThanks @Grisoly! - Exposes theCodecomponentlangprop type:#14111
5452ee6Thanks @ascorbic! - Fixes a bug that prevented "key" from being used as a prop for Astro components in MDX#14106
b5b39e4Thanks @ascorbic! - Exits with non-zero exit code when config has an error#14112
37458b3Thanks @ascorbic! - Fixes a bug that meant that SVG components could no longer be serialized withJSON.stringify#14061
c7a7dd5Thanks @jonasgeiler! - Add module declaration for?no-inlineasset imports#14109
5a08fa2Thanks @ascorbic! - Throw a more helpful error if defineLiveCollection is used outside of a live.config file#14110
e7dd4e1Thanks @ascorbic! - Warn if duplicate IDs are found by file loaderv5.12.1Compare Source
Patch Changes
#14094
22e9087Thanks @ascorbic! - Correct types to allowpriorityon all images#14091
26c6b6dThanks @ascorbic! - Fixes a bug that caused a type error when defining session options without a driver#14082
93322cbThanks @louisescher! - Fixes an issue where Astro's default 404 route would incorrectly match routes containing "/404" in dev#14089
687d253Thanks @florian-lefebvre! - Fixes a case whereastro:envwould not load the right environments variables in dev#14092
6692c71Thanks @ascorbic! - Improves error handling in live collections#14074
144a950Thanks @abcfy2! - Fixes a bug that caused some image service builds to fail#14092
6692c71Thanks @ascorbic! - Fixes a case where zod could not be imported fromastro:contentvirtual module in live collection configv5.12.0Compare Source
Minor Changes
#13971
fe35ee2Thanks @adamhl8! - Adds an experimental flagrawEnvValuesto disable coercion ofimport.meta.envvalues (e.g. converting strings to other data types) that are populated fromprocess.envAstro allows you to configure a type-safe schema for your environment variables, and converts variables imported via
astro:envinto the expected type.However, Astro also converts your environment variables used through
import.meta.envin some cases, and this can prevent access to some values such as the strings"true"(which is converted to a boolean value), and"1"(which is converted to a number).The
experimental.rawEnvValuesflag disables coercion ofimport.meta.envvalues that are populated fromprocess.env, allowing you to use the raw value.To enable this feature, add the experimental flag in your Astro config:
import { defineConfig } from "astro/config" export default defineConfig({ + experimental: { + rawEnvValues: true, + } })If you were relying on this coercion, you may need to update your project code to apply it manually:
See the experimental raw environment variables reference docs for more information.
#13941
6bd5f75Thanks @aditsachde! - Adds support for TOML files to Astro's built-inglob()andfile()content loaders.In Astro 5.2, Astro added support for using TOML frontmatter in Markdown files instead of YAML. However, if you wanted to use TOML files as local content collection entries themselves, you needed to write your own loader.
Astro 5.12 now directly supports loading data from TOML files in content collections in both the
glob()and thefile()loaders.If you had added your own TOML content parser for the
file()loader, you can now remove it as this functionality is now included:// src/content.config.ts import { defineCollection } from "astro:content"; import { file } from "astro/loaders"; - import { parse as parseToml } from "toml"; const dogs = defineCollection({ - loader: file("src/data/dogs.toml", { parser: (text) => parseToml(text) }), + loader: file("src/data/dogs.toml") schema: /* ... */ })Note that TOML does not support top-level arrays. Instead, the
file()loader considers each top-level table to be an independent entry. The table header is populated in theidfield of the entry object.See Astro's content collections guide for more information on using the built-in content loaders.
Patch Changes
6bd5f75]:v5.11.2Compare Source
Patch Changes
#14064
2eb77d8Thanks @jp-knj! - Allows usingtsconfigcompilerOptions.pathswithout settingcompilerOptions.baseUrl#14068
10189c0Thanks @jsparkdev! - Fixes the incorrect CSS import path shown in the terminal message during Tailwind integration setup.v5.11.1Compare Source
Patch Changes
#14045
3276b79Thanks @ghubo! - Fixes a problem where importing animated.aviffiles returns aNoImageMetadataerror.#14041
0c4d5f8Thanks @dixslyf! - Fixes a<ClientRouter />bug where the fallback view transition animations when exiting a pageran too early for browsers that do not support the View Transition API.
This bug prevented
event.viewTransition?.skipTransition()from skipping the page exit animationwhen used in an
astro:before-swapevent hook.v5.11.0Compare Source
Minor Changes
#13972
db8f8beThanks @ematipico! - Updates theNodeApp.match()function in the Adapter API to accept a second, optional parameter to allow adapter authors to add headers to static, prerendered pages.NodeApp.match(request)currently checks whether there is a route that matches the givenRequest. If there is a prerendered route, the function returnsundefined, because static routes are already rendered and their headers cannot be updated.When the new, optional boolean parameter is passed (e.g.
NodeApp.match(request, true)), Astro will return the first matched route, even when it's a prerendered route. This allows your adapter to now access static routes and provides the opportunity to set headers for these pages, for example, to implement a Content Security Policy (CSP).Patch Changes
#14029
42562f9Thanks @ematipico! - Fixes a bug where server islands wouldn't be correctly rendered when they are rendered inside fragments.Now the following examples work as expected:
v5.10.2Compare Source
Patch Changes
#14000
3cbedaeThanks @feelixe! - Fix routePattern JSDoc examples to show correct return values#13990
de6cfd6Thanks @isVivek99! - Fixes a case whereastro:config/clientandastro:config/servervirtual modules would not contain config passed to integrationsupdateConfig()during the build#14019
a160d1eThanks @ascorbic! - Removes the requirement to settype: 'live'when defining experimental live content collectionsPreviously, live collections required a
typeandloaderconfigured. Now, Astro can determine that your collection is alivecollection without defining it explicitly.This means it is now safe to remove
type: 'live'from your collections defined insrc/live.config.ts:import { defineLiveCollection } from 'astro:content'; import { storeLoader } from '@​mystore/astro-loader'; const products = defineLiveCollection({ - type: 'live', loader: storeLoader({ apiKey: process.env.STORE_API_KEY, endpoint: 'https://api.mystore.com/v1', }), }); export const collections = { products };This is not a breaking change: your existing live collections will continue to work even if you still include
type: 'live'. However, we suggest removing this line at your earliest convenience for future compatibility when the feature becomes stable and this config option may be removed entirely.#13966
598da21Thanks @msamoylov! - Fixes a broken link on the default 404 page in developmentv5.10.1Compare Source
Patch Changes
#13988
609044cThanks @ascorbic! - Fixes a bug in live collections that caused it to incorrectly complain about the collection being defined in the wrong file#13909
b258d86Thanks @isVivek99! - Fixes rendering of special boolean attributes for custom elements#13983
e718375Thanks @florian-lefebvre! - Fixes a case where the toolbar audit would incorrectly flag images processed by Astro in content collections documents#13999
f077b68Thanks @ascorbic! - AddslastModifiedfield to experimental live collection cache hintsLive loaders can now set a
lastModifiedfield in the cache hints for entries and collections to indicate when the data was last modified. This is then available in thecacheHintfield returned bygetCollectionandgetEntry.#13987
08f34b1Thanks @ematipico! - Adds an informative message in dev mode when the CSP feature is enabled.#14005
82aad62Thanks @ematipico! - Fixes a bug where inline styles and scripts didn't work when CSP was enabled. Now when adding<styles>elements inside an Astro component, their hashes care correctly computed.#13985
0b4c641Thanks @jsparkdev! - Updates wrong linkv5.10.0Compare Source
Minor Changes
#13917
e615216Thanks @ascorbic! - Adds a newpriorityattribute for Astro's image components.This change introduces a new
priorityoption for the<Image />and<Picture />components, which automatically sets theloading,decoding, andfetchpriorityattributes to their optimal values for above-the-fold images which should be loaded immediately.It is a boolean prop, and you can use the shorthand syntax by simply adding
priorityas a prop to the<Image />or<Picture />component. When set, it will apply the following attributes:loading="eager"decoding="sync"fetchpriority="high"The individual attributes can still be set manually if you need to customize your images further.
By default, the Astro
<Image />component generates<img>tags that lazy-load their content by settingloading="lazy"anddecoding="async". This improves performance by deferring the loading of images that are not immediately visible in the viewport, and gives the best scores in performance audits like Lighthouse.The new
priorityattribute will override those defaults and automatically add the best settings for your high-priority assets.This option was previously available for experimental responsive images, but now it is a standard feature for all images.
Usage
#13917
e615216Thanks @ascorbic! - The responsive images feature introduced behind a flag in v5.0.0 is no longer experimental and is available for general use.The new responsive images feature in Astro automatically generates optimized images for different screen sizes and resolutions, and applies the correct attributes to ensure that images are displayed correctly on all devices.
Enable the
image.responsiveStylesoption in your Astro config. Then, set alayoutattribute on any or component, or configure a defaultimage.layout, for instantly responsive images with automatically generatedsrcsetandsizesattributes based on the image's dimensions and the layout type.Displaying images correctly on the web can be challenging, and is one of the most common performance issues seen in sites. This new feature simplifies the most challenging part of the process: serving your site visitor an image optimized for their viewing experience, and for your website's performance.
For full details, see the updated Image guide.
Migration from Experimental Responsive Images
The
experimental.responsiveImagesflag has been removed, and all experimental image configuration options have been renamed to their final names.If you were using the experimental responsive images feature, you'll need to update your configuration:
Remove the experimental flag
export default defineConfig({ experimental: { - responsiveImages: true, }, });Update image configuration options
During the experimental phase, default styles were applied automatically to responsive images. Now, you need to explicitly set the
responsiveStylesoption totrueif you want these styles applied.export default defineConfig({ image: { + responsiveStyles: true, }, });The experimental image configuration options have been renamed:
Before:
After:
Component usage remains the same
The
layout,fit, andpositionprops on<Image>and<Picture>components work exactly the same as before:If you weren't using the experimental responsive images feature, no changes are required.
Please see the Image guide for more information on using responsive images in Astro.
#13685
3c04c1fThanks @ascorbic! - Adds experimental support for live content collectionsLive content collections are a new type of content collection that fetch their data at runtime rather than build time. This allows you to access frequently-updated data from CMSs, APIs, databases, or other sources using a unified API, without needing to rebuild your site when the data changes.
Live collections vs build-time collections
In Astro 5.0, the content layer API added support for adding diverse content sources to content collections. You can create loaders that fetch data from any source at build time, and then access it inside a page via
getEntry()andgetCollection(). The data is cached between builds, giving fast access and updates.However there is no method for updating the data store between builds, meaning any updates to the data need a full site deploy, even if the pages are rendered on-demand. This means that content collections are not suitable for pages that update frequently. Instead, today these pages tend to access the APIs directly in the frontmatter. This works, but leads to a lot of boilerplate, and means users don't benefit from the simple, unified API that content loaders offer. In most cases users tend to individually create loader libraries that they share between pages.
Live content collections solve this problem by allowing you to create loaders that fetch data at runtime, rather than build time. This means that the data is always up-to-date, without needing to rebuild the site.
How to use
To enable live collections add the
experimental.liveContentCollectionsflag to yourastro.config.mjsfile:Then create a new
src/live.config.tsfile (alongside yoursrc/content.config.tsif you have one) to define your live collections with a live loader and optionally a schema using the newdefineLiveCollection()function from theastro:contentmodule.You can then use the dedicated
getLiveCollection()andgetLiveEntry()functions to access your live data:v5.9.4Compare Source
Patch Changes
#13951
7eb88f1Thanks @ascorbic! - Fixes a issue that caused errors when using an adapter-provided session driver with custom options#13953
448bddcThanks @zaitovalisher! - Fixes a bug where quotes were not added to the 'strict-dynamic' CSP directivev5.9.3Compare Source
Patch Changes
#13923
a9ac5edThanks @ematipico! - BREAKING CHANGE to the experimental Content Security Policy (CSP) onlyChanges the behavior of experimental Content Security Policy (CSP) to now serve hashes differently depending on whether or not a page is prerendered:
<meta>element for static pages.Responseheadercontent-security-policyfor on-demand rendered pages.This new strategy allows you to add CSP content that is not supported in a
<meta>element (e.g.report-uri,frame-ancestors, and sandbox directives) to on-demand rendered pages.No change to your project code is required as this is an implementation detail. However, this will result in a different HTML output for pages that are rendered on demand. Please check your production site to verify that CSP is working as intended.
To keep up to date with this developing feature, or to leave feedback, visit the CSP Roadmap proposal.
#13926
953a249Thanks @ematipico! - Adds a new Astro Adapter Feature calledexperimentalStaticHeadersto allow your adapter to receive theHeadersfor rendered static pages.Adapters that enable support for this feature can access header values directly, affecting their handling of some Astro features such as Content Security Policy (CSP). For example, Astro will no longer serve the CSP
<meta http-equiv="content-security-policy">element in static pages to adapters with this support.Astro will serve the value of the header inside a map that can be retrieved from the hook
astro:build:generated. Adapters can read this mapping and use their hosting headers capabilities to create a configuration file.A new field called
experimentalRouteToHeaderswill contain a map ofMap<IntegrationResolvedRoute, Headers>where theHeaderstype contains the headers emitted by the rendered static route.To enable support for this experimental Astro Adapter Feature, add it to your
adapterFeaturesin your adapter config:See the Adapter API docs for more information about providing adapter features.
#13697
af83b85Thanks @benosmac! - Fixes issues with fallback route pattern matching wheni18n.routing.fallbackTypeisrewrite.generatePathwhen building fallback routes and checking for existing translated pagesNow for a route to be matched it needs to be inside a named
[locale]folder. This fixes an issue whereroute.pattern.test()incorrectly matched dynamic routes, causing the page to be skipped.findRouteToRewriteNow the requested pathname must exist in
route.distURLfor a dynamic route to match. This fixes an issue whereroute.pattern.test()incorrectly matched dynamic routes, causing the build to fail.#13924
1cd8c3bThanks @qw-in! - Fixes an edge case whereisPrerenderedwas incorrectly set tofalsefor static redirects.#13926
953a249Thanks @ematipico! - Fixes an issue where the experimental CSPmetaelement wasn't placed in the<head>element as early as possible, causing these policies to not apply to styles and scripts that came before themetaelement.v5.9.2Compare Source
Patch Changes
#13919
423fe60Thanks @ematipico! - Fixes a bug where Astro added quotes to the CSP resources.Only certain resources require quotes (e.g.
'self'but nothttps://cdn.example.com), so Astro no longer adds quotes to any resources. You must now provide the quotes yourself for resources such as'self'when necessary:export default defineConfig({ experimental: { csp: { styleDirective: { resources: [ - "self", + "'self'", "https://cdn.example.com" ] } } } })#13914
76c5480Thanks @ematipico! - BREAKING CHANGE to the experimental Content Security Policy feature onlyRemoves support for experimental Content Security Policy (CSP) when using the
<ClientRouter />component for view transitions.It is no longer possible to enable experimental CSP while using Astro's view transitions. Support was already unstable with the
<ClientRouter />because CSP required making its underlying implementation asynchronous. This caused breaking changes for several users and therefore, this PR removes support completely.If you are currently using the component for view transitions, please remove the experimental CSP flag as they cannot be used together.
import { defineConfig } from 'astro/config'; export default defineConfig({ experimental: { - csp: true } });Alternatively, to continue using experimental CSP in your project, you can consider migrating to the browser native View Transition API and remove the
<ClientRouter />from your project. You may be able to achieve similar results if you are not using Astro's enhancements to the native View Transitions and Navigation APIs.Support might be reintroduced in future releases. You can follow this experimental feature's development in the CSP RFC.
v5.9.1Compare Source
Patch Changes
#13899
7a1303dThanks @reknih! - Fix bug where error pages would return invalid bodies if the upstream response was compressed#13902
051bc30Thanks @arHSM! - Fixes a bug where vite virtual module ids were incorrectly added in the dev server#13905
81f71caThanks @jsparkdev! - Fixes wrong contents in CSP meta tag.#13907
8246bccThanks @martrapp! - Fixes a bug that caused view transition names to be lost.#13901
37fa0a2Thanks @ansg191! - fix fallback not being removed when server island is renderedv5.9.0Compare Source
Minor Changes
#13802
0eafe14Thanks @ematipico! - Adds experimental Content Security Policy (CSP) supportCSP is an important feature to provide fine-grained control over resources that can or cannot be downloaded and executed by a document. In particular, it can help protect against cross-site scripting (XSS) attacks.
Enabling this feature adds additional security to Astro's handling of processed and bundled scripts and styles by default, and allows you to further configure these, and additional, content types. This new experimental feature has been designed to work in every Astro rendering environment (static pages, dynamic pages and single page applications), while giving you maximum flexibility and with type-safety in mind.
It is compatible with most of Astro's features such as client islands, and server islands, although Astro's view transitions using the
<ClientRouter />are not yet fully supported. Inline scripts are not supported out of the box, but you can provide your own hashes for external and inline scripts.To enable this feature, add the experimental flag in your Astro config:
For more information on enabling and using this feature in your project, see the Experimental CSP docs.
For a complete overview, and to give feedback on this experimental API, see the Content Security Policy RFC.
#13850
1766d22Thanks [@ascorbic](https://redireConfiguration
📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR was generated by Mend Renovate. View the repository job log.