,
+ MyDurableObject: MyDurableObject,
+ }
+}
+```
+
## Cloudflare runtime
### Usage
diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx
index 70098480f890d..30d842068da64 100644
--- a/src/content/docs/en/reference/configuration-reference.mdx
+++ b/src/content/docs/en/reference/configuration-reference.mdx
@@ -1133,65 +1133,78 @@ You can use wildcards to define the permitted `hostname` and `pathname` values a
- End with '/**' to allow all sub-routes ('startsWith').
- End with '/*' to allow only one level of sub-route.
-### image.experimentalLayout
+### image.responsiveStyles
+
+
+
+**Type:** `boolean`
+**Default:** `false`
+
+
+
+Whether to automatically add global styles for responsive images. You should enable this option unless you are styling the images yourself.
+
+This option is only used when `layout` is set to `constrained`, `full-width`, or `fixed` using the configuration or the `layout` prop on the image component.
+
+See [the Images guide](/en/guides/images/#responsive-image-styles) for more information.
+
+
+### image.layout
**Type:** `ImageLayout`
-**Default:** `undefined`
+**Default:** `undefined`
+
The default layout type for responsive images. Can be overridden by the `layout` prop on the image component.
-Requires the `experimental.responsiveImages` flag to be enabled.
- `constrained` - The image will scale to fit the container, maintaining its aspect ratio, but will not exceed the specified dimensions.
- `fixed` - The image will maintain its original dimensions.
- `full-width` - The image will scale to fit the container, maintaining its aspect ratio.
-### image.experimentalObjectFit
+See [the `layout` component property](/en/reference/modules/astro-assets/#layout) for more details.
+
+### image.objectFit
**Type:** `ImageFit`
-**Default:** `"cover"`
+**Default:** `"cover"`
+
-The default object-fit value for responsive images. Can be overridden by the `fit` prop on the image component.
-Requires the `experimental.responsiveImages` flag to be enabled.
+The [`object-fit` CSS property value](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) for responsive images. Can be overridden by the `fit` prop on the image component.
+Requires a value for `layout` to be set.
+
+See [the `fit` component property](/en/reference/modules/astro-assets/#fit) for more details.
-### image.experimentalObjectPosition
+### image.objectPosition
**Type:** `string`
-**Default:** `"center"`
+**Default:** `"center"`
+
-The default object-position value for responsive images. Can be overridden by the `position` prop on the image component.
-Requires the `experimental.responsiveImages` flag to be enabled.
+The default [`object-position` CSS property value](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) for responsive images. Can be overridden by the `position` prop on an individual image component. Requires a value for `layout` to be set.
+
+See [the `position` component property](/en/reference/modules/astro-assets/#position) for more details.
-### image.experimentalBreakpoints
+### image.breakpoints
**Type:** `Array`
-**Default:** `[640, 750, 828, 1080, 1280, 1668, 2048, 2560] | [640, 750, 828, 960, 1080, 1280, 1668, 1920, 2048, 2560, 3200, 3840, 4480, 5120, 6016]`
+**Default:** `[640, 750, 828, 1080, 1280, 1668, 2048, 2560] | [640, 750, 828, 960, 1080, 1280, 1668, 1920, 2048, 2560, 3200, 3840, 4480, 5120, 6016]`
+
-The breakpoints used to generate responsive images. Requires the `experimental.responsiveImages` flag to be enabled. The full list is not normally used,
+The breakpoints used to generate responsive images. Requires a value for `layout` to be set. The full list is not normally used,
but is filtered according to the source and output size. The defaults used depend on whether a local or remote image service is used. For remote services
the more comprehensive list is used, because only the required sizes are generated. For local services, the list is shorter to reduce the number of images generated.
-### image.experimentalDefaultStyles
-
-
-
-**Type:** `boolean`
-**Default:** `true`
-
-
-Whether to automatically add global styles to ensure that experimental images resize correctly. This is enabled by default, but can be disabled if you want to manage the styles yourself.
-This option is only used when the `experimental.responsiveImages` flag is enabled.
-
## Markdown Options
diff --git a/src/content/docs/en/reference/error-reference.mdx b/src/content/docs/en/reference/error-reference.mdx
index 61cebf144e16c..4c00307257b25 100644
--- a/src/content/docs/en/reference/error-reference.mdx
+++ b/src/content/docs/en/reference/error-reference.mdx
@@ -126,6 +126,7 @@ The following reference is a complete list of the errors you may encounter while
- [**InvalidContentEntryDataError**](/en/reference/errors/invalid-content-entry-data-error/)
Content entry data does not match schema.
- [**ContentLoaderReturnsInvalidId**](/en/reference/errors/content-loader-returns-invalid-id/)
Content loader returned an entry with an invalid `id`.
- [**ContentEntryDataError**](/en/reference/errors/content-entry-data-error/)
Content entry data does not match schema.
+- [**LiveContentConfigError**](/en/reference/errors/live-content-config-error/)
Error in live content config.
- [**ContentLoaderInvalidDataError**](/en/reference/errors/content-loader-invalid-data-error/)
Content entry is missing an ID
- [**InvalidContentEntrySlugError**](/en/reference/errors/invalid-content-entry-slug-error/)
Invalid content entry slug.
- [**ContentSchemaContainsSlugError**](/en/reference/errors/content-schema-contains-slug-error/)
Content Schema should not contain `slug`.
diff --git a/src/content/docs/en/reference/errors/live-content-config-error.mdx b/src/content/docs/en/reference/errors/live-content-config-error.mdx
new file mode 100644
index 0000000000000..4e47e136fadb0
--- /dev/null
+++ b/src/content/docs/en/reference/errors/live-content-config-error.mdx
@@ -0,0 +1,25 @@
+---
+# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs'
+# Do not make edits to it directly, they will be overwritten.
+# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+# Translators, please remove this note and the component.
+
+title: Error in live content config.
+i18nReady: true
+githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+---
+import DontEditWarning from '~/components/DontEditWarning.astro'
+
+
+
+
+> **Example error message:**
+The schema cannot be a function for live collections. Please use a schema object instead. Check your collection definitions in your live content config file.
+
+## What went wrong?
+Error in live content config.
+
+**See Also:**
+- [Experimental live content](https://astro.build/en/reference/experimental-flags/live-content-collections/)
+
+
diff --git a/src/content/docs/en/reference/experimental-flags/live-content-collections.mdx b/src/content/docs/en/reference/experimental-flags/live-content-collections.mdx
new file mode 100644
index 0000000000000..fb638c472a08b
--- /dev/null
+++ b/src/content/docs/en/reference/experimental-flags/live-content-collections.mdx
@@ -0,0 +1,611 @@
+---
+title: Experimental live content collections
+sidebar:
+ label: Live content collections
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro';
+
+
+
+**Type:** `boolean`
+**Default:** `false`
+
+
+
+
+Enables support for live content collections in your project.
+
+Live content collections are a new type of [content collection](/en/guides/content-collections/) 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.
+
+## Basic usage
+
+To enable the feature, add the `experimental.liveContentCollections` flag to your `astro.config.mjs` file:
+
+```js title="astro.config.mjs"
+{
+ 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](#creating-a-live-loader) and optionally a [schema](#using-zod-schemas) using the new `defineLiveCollection()` function from the `astro:content` module.
+
+```ts title="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 };
+```
+
+You can then use the dedicated `getLiveCollection()` and `getLiveEntry()` functions to access your live data:
+
+```astro
+---
+import { getLiveCollection, getLiveEntry } from 'astro:content';
+
+// Get all products
+const { entries: allProducts, error } = await getLiveCollection('products');
+if (error) {
+ // Handle error appropriately
+ console.error(error.message);
+}
+
+// Get products with a filter (if supported by your loader)
+const { entries: electronics } = await getLiveCollection('products', { category: 'electronics' });
+
+// Get a single product by ID (string syntax)
+const { entry: product, error: productError } = await getLiveEntry('products', Astro.params.id);
+if (productError) {
+ return Astro.redirect('/404');
+}
+
+// Get a single product with a custom query (if supported by your loader) using a filter object
+const { entry: productBySlug } = await getLiveEntry('products', { slug: Astro.params.slug });
+---
+```
+
+## When to use live content collections
+
+Live content collections are designed for data that changes frequently and needs to be up-to-date when a page is requested. Consider using them when:
+
+- **You need real-time information** (e.g. user-specific data, current stock levels)
+- **You want to avoid constant rebuilds** for content that changes often
+- **Your data updates frequently** (e.g. up-to-the-minute product inventory, prices, availability)
+- **You need to pass dynamic filters** to your data source based on user input or request parameters
+- **You're building preview functionality** for a CMS where editors need to see draft content immediately
+
+In contrast, use build-time content collections when:
+
+- **Performance is critical** and you want to pre-render data at build time
+- **Your data is relatively static** (e.g., blog posts, documentation, product descriptions)
+- **You want to benefit from build-time optimization** and caching
+- **You need to process MDX** or perform image optimization
+- **Your data can be fetched once and reused** across multiple builds
+
+See the [limitations of experimental live collections](#live-collection-limitations) and [key differences from build-time collections](#differences-from-build-time-collections) for more details on choosing between live and preloaded collections.
+
+## Using live collections
+
+You can [create your own live loaders](#creating-a-live-loader) for your data source, or you can use community loaders distributed as npm packages. Here's how you could use example CMS and e-commerce loaders:
+
+```ts title="src/live.config.ts"
+import { defineLiveCollection } from 'astro:content';
+import { cmsLoader } from '@example/cms-astro-loader';
+import { productLoader } from '@example/store-astro-loader';
+
+const articles = defineLiveCollection({
+ type: 'live',
+ loader: cmsLoader({
+ apiKey: process.env.CMS_API_KEY,
+ contentType: 'article',
+ }),
+});
+
+const products = defineLiveCollection({
+ type: 'live',
+ loader: productLoader({
+ apiKey: process.env.STORE_API_KEY,
+ }),
+});
+
+export const collections = { articles, authors };
+```
+
+You can then get content from both loaders with a unified API:
+
+```astro
+---
+import { getLiveCollection, getLiveEntry } from 'astro:content';
+
+// Use loader-specific filters
+const { entries: draftArticles } = await getLiveCollection('articles', {
+ status: 'draft',
+ author: 'john-doe',
+});
+
+// Get a specific product by ID
+const { entry: product } = await getLiveEntry('products', Astro.params.slug);
+---
+```
+
+### Error handling
+
+Live loaders can fail due to network issues, API errors, or validation problems. The API is designed to make error handling explicit.
+
+When you call `getLiveCollection()` or `getLiveEntry()`, the error will be one of:
+
+- The error type defined by the loader (if it returned an error)
+- A `LiveEntryNotFoundError` if the entry was not found
+- A `LiveCollectionValidationError` if the collection data does not match the expected schema
+- A `LiveCollectionCacheHintError` if the cache hint is invalid
+- A `LiveCollectionError` for other errors, such as uncaught errors thrown in the loader
+
+These errors have a static `is()` method that you can use to check the type of error at runtime:
+
+```astro "LiveEntryNotFoundError.is(error)"
+---
+import { getLiveEntry, LiveEntryNotFoundError } from 'astro:content';
+const { entry, error } = await getLiveEntry('products', Astro.params.id);
+if (error) {
+ if (LiveEntryNotFoundError.is(error)) {
+ console.error(`Product not found: ${error.message}`);
+ Astro.response.status = 404;
+ } else {
+ console.error(`Error loading product: ${error.message}`);
+ return Astro.redirect('/500');
+ }
+}
+---
+```
+
+## Creating a live loader
+
+A live loader is an object with two methods: `loadCollection()` and `loadEntry()`. These methods should handle errors gracefully and return either data or an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object.
+
+The standard pattern is to export a function that returns this loader object, allowing you to pass configuration options like API keys or endpoints.
+
+Here's a basic example:
+
+```ts title="myloader.ts"
+import type { LiveLoader } from 'astro/loaders';
+import { fetchFromCMS } from './cms-client.js';
+
+interface Article {
+ id: string;
+ title: string;
+ content: string;
+ author: string;
+}
+
+export function articleLoader(config: { apiKey: string }): LiveLoader {
+ return {
+ name: 'article-loader',
+ loadCollection: async ({ filter }) => {
+ try {
+ const articles = await fetchFromCMS({
+ apiKey: config.apiKey,
+ type: 'article',
+ filter,
+ });
+
+ return {
+ entries: articles.map((article) => ({
+ id: article.id,
+ data: article,
+ })),
+ };
+ } catch (error) {
+ return {
+ error: new Error(`Failed to load articles: ${error.message}`),
+ };
+ }
+ },
+ loadEntry: async ({ filter }) => {
+ try {
+ // filter will be { id: "some-id" } when called with a string
+ const article = await fetchFromCMS({
+ apiKey: config.apiKey,
+ type: 'article',
+ id: filter.id,
+ });
+
+ if (!article) {
+ return {
+ error: new Error('Article not found'),
+ };
+ }
+
+ return {
+ id: article.id,
+ data: article,
+ };
+ } catch (error) {
+ return {
+ error: new Error(`Failed to load article: ${error.message}`),
+ };
+ }
+ },
+ };
+}
+```
+
+### Rendering content
+
+A loader can add support for directly rendered content by returning [a `rendered` property](/en/reference/content-loader-reference/#rendered) in the entry. This allows you to use [the `render()` function and `` component](/en/guides/content-collections/#rendering-body-content) to render the content directly in your pages.
+If the loader does not return a `rendered` property for an entry, the `` component will render nothing.
+
+```ts title="myloader.ts" {16-19}
+// ...
+export function articleLoader(config: { apiKey: string }): LiveLoader {
+ return {
+ name: 'article-loader',
+ loadEntry: async ({ filter }) => {
+ try {
+ const article = await fetchFromCMS({
+ apiKey: config.apiKey,
+ type: 'article',
+ id: filter.id,
+ });
+
+ return {
+ id: article.id,
+ data: article,
+ rendered: {
+ // Assuming the CMS returns HTML content
+ html: article.htmlContent,
+ },
+ };
+ } catch (error) {
+ return {
+ error: new Error(`Failed to load article: ${error.message}`),
+ };
+ }
+ },
+ // ...
+ };
+}
+```
+
+You can then render both content and metadata from live collection entries in pages using the same method as built-time collections. You also have access to any [error returned by the live loader](#error-handling-in-loaders), for example, to rewrite to a 404 page when content cannot be displayed:
+
+```astro "render(entry)" ""
+---
+import { getLiveEntry, render } from 'astro:content';
+const { entry, error } = await getLiveEntry('articles', Astro.params.id);
+if (error) {
+ return Astro.rewrite('/404');
+}
+
+const { Content } = await render(entry);
+---
+
+{entry.data.title}
+
+```
+
+### Error handling in loaders
+
+Loaders should handle all errors and return an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) subclass for errors. You can create custom error types and use them for more specific error handling if needed. If an error is thrown in the loader, it will be caught and returned, wrapped in a `LiveCollectionError`. You can also create [custom error types](#custom-error-types) for proper typing.
+
+Astro will generate some errors itself, depending on the response from the loader:
+
+- If `loadEntry` returns `undefined`, Astro will return a `LiveEntryNotFoundError` to the user.
+- If a schema is defined for the collection and the data does not match the schema, Astro will return a `LiveCollectionValidationError`.
+- If the loader returns an invalid cache hint, Astro will return a `LiveCollectionCacheHintError`. The `cacheHint` field is optional, so if you do not have valid data to return, you can simply omit it.
+
+```ts title="my-loader.ts" {6-8}
+import type { LiveLoader } from 'astro/loaders';
+import { MyLoaderError } from './errors.js';
+
+export function myLoader(config): LiveLoader {
+ return {
+ name: 'my-loader',
+ loadCollection: async ({ filter }) => {
+ // Return your custom error type
+ return {
+ error: new MyLoaderError('Failed to load', 'LOAD_ERROR'),
+ };
+ },
+ // ...
+ };
+}
+```
+
+### Distributing your loader
+
+Loaders can be defined in your site or as a separate npm package. If you want to share your loader with the community, you can [publish it to NPM with the `astro-component` and `astro-loader` keywords](/en/reference/publish-to-npm/#packagejson-data).
+
+The loader should export a function that returns the `LiveLoader` object, allowing users to configure it with their own settings.
+
+## Type safety
+
+Like regular content collections, live collections can be typed to ensure type safety in your data. [Using Zod schemas](#using-zod-schemas) is supported, but not required to define types for live collections. Unlike preloaded collections defined at build time, live loaders can instead choose to pass generic types to the `LiveLoader` interface.
+You can define the types for your collection and entry data, as well as custom filter types for querying, and custom error types for error handling.
+
+### Type-safe data
+
+Live loaders can define types for the data they return. This allows TypeScript to provide type checking and autocompletion when working with the data in your components.
+
+```ts title="store-loader.ts" "LiveLoader" "type Product"
+import type { LiveLoader } from 'astro/loaders';
+import { fetchProduct, fetchCategory, type Product } from './store-client';
+
+export function storeLoader(): LiveLoader {
+ // ...
+}
+```
+
+When you use `getLiveCollection()` or `getLiveEntry()`, TypeScript will infer the types based on the loader's definition:
+
+```astro
+---
+import { getLiveEntry } from 'astro:content';
+const { entry: product } = await getLiveEntry('products', '123');
+// TypeScript knows product.data is of type Product
+console.log(product?.data.name);
+---
+```
+
+### Type-safe filters
+
+Live loaders can define custom filter types for both `getLiveCollection()` and `getLiveEntry()`. This enables type-safe querying that matches your API's capabilities, making it easier for users to discover available filters and ensure they are used correctly. If you include JSDoc comments in your filter types, the user will see these in their IDE as hints when using the loader.
+
+```ts title="store-loader.ts" "EntryFilter, CollectionFilter" {6,8}
+import type { LiveLoader } from 'astro/loaders';
+import { fetchProduct, fetchCategory, type Product } from './store-client';
+
+interface CollectionFilter {
+ category?: string;
+ /** Minimum price to filter products */
+ minPrice?: number;
+ /** Maximum price to filter products */
+ maxPrice?: number;
+}
+
+interface EntryFilter {
+ /** Alias for `sku` */
+ id?: string;
+ slug?: string;
+ sku?: string;
+}
+
+export function productLoader(config: {
+ apiKey: string;
+ endpoint: string;
+}): LiveLoader {
+ return {
+ name: 'product-loader',
+ loadCollection: async ({ filter }) => {
+ // filter is typed as CollectionFilter
+ const data = await fetchCategory({
+ apiKey: config.apiKey,
+ category: filter?.category ?? 'all',
+ minPrice: filter?.minPrice,
+ maxPrice: filter?.maxPrice,
+ });
+
+ return {
+ entries: data.products.map((product) => ({
+ id: product.sku,
+ data: product,
+ })),
+ };
+ },
+ loadEntry: async ({ filter }) => {
+ // filter is typed as EntryFilter | { id: string }
+ const product = await fetchProduct({
+ apiKey: config.apiKey,
+ slug: filter.slug,
+ sku: filter.sku || filter.id,
+ });
+ if (!product) {
+ return {
+ error: new Error('Product not found'),
+ };
+ }
+ return {
+ id: product.sku,
+ entry: product,
+ };
+ },
+ };
+}
+```
+
+### Custom error types
+
+You can create custom error types for [errors returned by your loader](#error-handling-in-loaders) and pass them as a generic to get proper typing:
+
+```ts title="my-loader.ts"
+class MyLoaderError extends Error {
+ constructor(
+ message: string,
+ public code?: string
+ ) {
+ super(message);
+ this.name = 'MyLoaderError';
+ }
+}
+
+export function myLoader(config): LiveLoader {
+ return {
+ name: 'my-loader',
+ loadCollection: async ({ filter }) => {
+ // Return your custom error type
+ return {
+ error: new MyLoaderError('Failed to load', 'LOAD_ERROR'),
+ };
+ },
+ // ...
+ };
+}
+```
+
+When you use `getLiveCollection()` or `getLiveEntry()`, TypeScript will infer the custom error type, allowing you to handle it appropriately:
+
+```astro
+---
+import { getLiveEntry } from 'astro:content';
+const { entry, error } = await getLiveEntry('products', '123');
+if (error) {
+ if (error.name === 'MyLoaderError') {
+ console.error(`Loader error: ${error.message} (code: ${error.code})`);
+ } else {
+ console.error(`Unexpected error: ${error.message}`);
+ }
+ return Astro.rewrite('/500');
+}
+---
+```
+
+## Using Zod schemas
+
+Just like with build-time collections, you can use [Zod schemas](/en/guides/content-collections/#defining-the-collection-schema) with live collections to validate and transform data at runtime. When you define a schema, it takes precedence over [the loader's types](#type-safe-data) when you query the collection:
+
+```ts title="src/live.config.ts"
+import { z, defineLiveCollection } from 'astro:content';
+import { apiLoader } from './loaders/api-loader';
+
+const products = defineLiveCollection({
+ type: 'live',
+ loader: apiLoader({ endpoint: process.env.API_URL }),
+ schema: z
+ .object({
+ id: z.string(),
+ name: z.string(),
+ price: z.number(),
+ // Transform the API's category format
+ category: z.string().transform((str) => str.toLowerCase().replace(/\s+/g, '-')),
+ // Coerce the date to a Date object
+ createdAt: z.coerce.date(),
+ })
+ .transform((data) => ({
+ ...data,
+ // Add a formatted price field
+ displayPrice: `$${data.price.toFixed(2)}`,
+ })),
+});
+
+export const collections = { products };
+```
+
+When using Zod schemas, validation errors are automatically caught and returned as `AstroError` objects:
+
+```astro
+---
+import { getLiveEntry, LiveCollectionValidationError } from 'astro:content';
+
+const { entry, error } = await getLiveEntry('products', '123');
+
+// You can handle validation errors specifically
+if (LiveCollectionValidationError.is(error)) {
+ console.error(error.message);
+ return Astro.rewrite('/500');
+}
+
+// TypeScript knows entry.data matches your Zod schema, not the loader's type
+console.log(entry?.data.displayPrice); // e.g., "$29.99"
+---
+```
+
+## Cache hints
+
+Live loaders can provide cache hints to help with response caching. You can use this data to send HTTP cache headers or otherwise inform your caching strategy.
+
+```ts title="my-loader.ts"
+export function myLoader(config): LiveLoader {
+ return {
+ name: 'cached-loader',
+ loadCollection: async ({ filter }) => {
+ // ... fetch data
+ return {
+ entries: data.map((item) => ({
+ id: item.id,
+ data: item,
+ // You can optionally provide cache hints for each entry
+ // These are merged with the collection's cache hint
+ cacheHint: {
+ tags: [`product-${item.id}`, `category-${item.category}`],
+ },
+ })),
+ cacheHint: {
+ tags: ['products'],
+ maxAge: 300, // 5 minutes
+ },
+ };
+ },
+ loadEntry: async ({ filter }) => {
+ // ... fetch single item
+ return {
+ id: item.id,
+ data: item,
+ cacheHint: {
+ tags: [`product-${item.id}`, `category-${item.category}`],
+ maxAge: 3600, // 1 hour
+ },
+ };
+ },
+ };
+}
+```
+
+You can then use these hints in your pages:
+
+```astro
+---
+import { getLiveEntry } from 'astro:content';
+
+const { entry, error, cacheHint } = await getLiveEntry('products', Astro.params.id);
+
+if (error) {
+ return Astro.redirect('/404');
+}
+
+// Apply cache hints to response headers
+if (cacheHint) {
+ Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
+ Astro.response.headers.set('Cache-Control', `s-maxage=${cacheHint.maxAge}`);
+}
+---
+
+{entry.data.name}
+{entry.data.description}
+```
+
+:::note
+Cache hints only provide values that can be used in other parts of your project and do not automatically cause the response to be cached by Astro. You can use them to create your own caching strategy, such as setting HTTP headers or using a CDN.
+:::
+
+## Live collection limitations
+
+Live content collections have some limitations compared to build-time collections:
+
+- **No MDX support**: MDX cannot be rendered at runtime
+- **No image optimization**: Images cannot be processed at runtime
+- **Performance considerations**: Data is fetched on each request (unless cached)
+- **No data store persistence**: Data is not saved to the content layer data store
+
+## Differences from build-time collections
+
+Live collections use a different API than current preloaded content collections. Key differences include:
+
+1. **Execution time**: Runs at request time instead of build time
+1. **Configuration file**: Use `src/live.config.ts` instead of `src/content.config.ts`
+1. **Collection definition**: Use `defineLiveCollection()` instead of `defineCollection()`
+1. **Collection type**: Set `type: "live"` in collection definition
+1. **Loader API**: Implement `loadCollection` and `loadEntry` methods instead of the `load` method
+1. **Data return**: Return data directly instead of storing in the data store
+1. **User-facing functions**: Use `getLiveCollection`/`getLiveEntry` instead of `getCollection`/`getEntry`
+
+For a complete overview and to give feedback on this experimental API, see the [Live Content collections RFC](https://github.com/withastro/roadmap/blob/feat/live-loaders/proposals/0055-live-content-loaders.md).
diff --git a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx b/src/content/docs/en/reference/experimental-flags/responsive-images.mdx
deleted file mode 100644
index 1aefa7a9b4851..0000000000000
--- a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx
+++ /dev/null
@@ -1,178 +0,0 @@
----
-title: Experimental responsive images
-sidebar:
- label: Responsive images
-i18nReady: true
----
-
-import Since from '~/components/Since.astro'
-
-
-
-**Type:** `boolean`
-**Default:** `false`
-
-
-
-Enables support for automatic responsive images in your project.
-
-The term [responsive images](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images) refers images that work well on different devices. This particularly applies to images that resize to fit their container, and that can be served in different sizes depending on the device's screen size and resolution.
-
-There are a number of additional properties that can be set to control how the image is displayed, but these can be complicated to handle manually. Incorrect handling of these properties can lead to images that are slow to download or that are not displayed correctly. This is one of the most common causes of poor Core Web Vitals and Lighthouse performance scores.
-
-When this flag is enabled, Astro can automatically generate the required `srcset` and `sizes` values for images, and apply the correct styles to ensure they resize correctly. This behavior can be configured globally or on a per-image basis.
-
-To enable the feature, first add the `responsiveImages` flag to your `astro.config.mjs` file:
-
-```js title="astro.config.mjs"
-{
- experimental: {
- responsiveImages: true,
- },
-}
-```
-
-Enabling this flag will not change anything by default, but responsive images can then be configured by setting the [image layout](#image-layout) either globally or per image.
-
-To do this, you have access to additional [`image` configuration settings](#configuration-settings) for controlling the default behavior of all images processed and optimized by Astro:
-
-- Local and remote images using [the Markdown `![]()` syntax](/en/guides/images/#images-in-markdown-files).
-- The [``](/en/guides/images/#display-optimized-images-with-the-image--component) and [``](/en/guides/images/#create-responsive-images-with-the-picture--component) components.
-
-Additionally, Astro's image components can receive [responsive image props](#responsive-image-properties) to override these defaults on a per-image basis.
-
-Images in your `public/` folder are never optimized, and responsive images are not supported.
-
-:::note
-Enabling responsive images will generate additional image sizes for all affected images. For prerendered pages this happens during the build so may increase the build time of your project, especially if you have a large number of images.
-
-For pages rendered on-demand the images are generated as-needed, so this has no impact on build times but may increase the number of transformations performed. Depending on your image service this may incur additional costs.
-:::
-
-## Image layout
-
-In order to generate the correct `srcset` and `sizes` attributes, the `` and `` components need to know how the image should resize when its container changes size. This is done by setting the `layout` prop, or `image.experimentalLayout` default. The supported values are:
-
-- `constrained` - The image will scale down to fit the container, maintaining its aspect ratio, but will not scale up beyond the specified `width` and `height`, or the image's original dimensions. Use this if you want the image to display at the requested size where possible, but shrink to fit smaller screens. This matches the default behavior for images when using Tailwind. If you're not sure, this is probably the layout you should choose.
-- `full-width` - The image will scale to fit the width of the container, maintaining its aspect ratio. Use this for hero images or other images that should take up the full width of the page.
-- `fixed` - The image will maintain the requested dimensions and not resize. It will generate a `srcset` to support high density displays, but not for different screen sizes. Use this if the image will not resize, for example icons or logos smaller than any screen width, or other images in a fixed-width container.
-- `none` - The image will not be responsive. No `srcset` or `sizes` will be automatically generated, and no styles will be applied. This is useful if you have enabled a default layout, but want to disable it for a specific image.
-
-The chosen `layout` will be used to generate the correct `srcset` and `sizes` attributes for the image, and will define the default styles applied to that `![]()
` tag.
-
-## Configuration settings
-
-Set [`image.experimentalLayout`](/en/reference/configuration-reference/#imageexperimentallayout) with a default value to enable responsive images throughout your project.
-
-If this value is not configured, you can still pass a `layout` prop to any `` or `` component to create a responsive image. However, Markdown images will not be responsive.
-
-Optionally, you can configure [`image.experimentalObjectFit`](/en/reference/configuration-reference/#imageexperimentalobjectfit) and [`image.experimentalObjectPosition`](/en/reference/configuration-reference/#imageexperimentalobjectposition) which will apply to all processed images by default.
-
-Each of these settings can be overridden on any individual `` or `` component with a prop, but Markdown images will always use the default settings.
-
-```js title="astro.config.mjs"
-{
- image: {
- // Used for all Markdown images; not configurable per-image
- // Used for all `` and `` components unless overridden with a prop
- experimentalLayout: 'constrained',
- },
- experimental: {
- responsiveImages: true,
- },
-}
-```
-
-## Responsive image properties
-
-These are additional properties available to the `` and `` components when responsive images are enabled:
-
-- `layout`: The [layout type](#image-layout) for the image. Can be `constrained`, `fixed`, `full-width`, or `none`. If set to `none`, responsive behavior is disabled for this image and all other options are ignored. Defaults to `none`, or the value of [`image.experimentalLayout`](/en/reference/configuration-reference/#imageexperimentallayout) if set.
-- `fit`: Defines how the image should be cropped if the aspect ratio is changed. Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`image.experimentalObjectFit`](/en/reference/configuration-reference/#imageexperimentalobjectfit) if set.
-- `position`: Defines the position of the image crop if the aspect ratio is changed. Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.experimentalObjectPosition`](/en/reference/configuration-reference/#imageexperimentalobjectposition) if set.
-- `priority`: If set, eagerly loads the image. Otherwise, images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to `false`.
-
-The `widths` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type, and in most cases should not be set manually. The generated `sizes` attribute for `constrained` and `full-width` images
-is based on the assumption that the image is displayed at close to the full width of the screen when the viewport is smaller than the image's width. If it is significantly different (e.g. if it's in a multi-column layout on small screens) you may need to adjust the `sizes` attribute manually for best results.
-
-The `densities` attribute is not compatible with responsive images and will be ignored if set.
-
-For example, with `constrained` set as the default layout, you can override any individual image's `layout` property:
-
-```astro
----
-import { Image } from 'astro:assets';
-import myImage from '../assets/my_image.png';
----
-
-
-
-```
-
-## Generated HTML output for responsive images
-
-When a layout is set, either by default or on an individual component, images have automatically generated `srcset` and `sizes` attributes based on the image's dimensions and the layout type. Images with `constrained` and `full-width` layouts will have styles applied to ensure they resize according to their container.
-
-```astro title=MyComponent.astro
----
-import { Image, Picture } from 'astro:assets';
-import myImage from '../assets/my_image.png';
----
-
-
-```
-
-This `` component will generate the following HTML output:
-
-```html
-
-```
-
-## Default responsive image styles
-
-The responsive image component applies a small number of styles to ensure they resize correctly. The applied styles depend on the layout type, and are designed to give the best behavior for the generated `srcset` and `sizes` attributes:
-
-```css title="Responsive Image Styles"
-:where([data-astro-image]) {
- object-fit: var(--fit);
- object-position: var(--pos);
-}
-:where([data-astro-image='full-width']) {
- width: 100%;
-}
-:where([data-astro-image='constrained']) {
- max-width: 100%;
-}
-```
-
-### Overriding default styles
-
-The styles use the [`:where()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which has a [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) of 0, meaning that it is easy to override with your own styles. Any CSS selector will have a higher specificity than `:where()`, so you can easily override the styles by adding your own styles to target the image.
-
-You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `` or `` component.
-
-You can disable the default styles entirely by setting [`image.experimentalDefaultStyles`](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) to `false` if you prefer to handle styling responsive images yourself.
-
-#### Tailwind 4
-
-Tailwind 4 is a special case, because it uses [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer), meaning the Tailwind rules are always lower specificity than rules that don't use layers. Astro supports browsers that do not support cascade layers, so it cannot use them for images. This means that [you should disable the default styles](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) if you need to override them with Tailwind 4.
-
-For a complete overview, and to give feedback on this experimental API, see the [Responsive Images RFC](https://github.com/withastro/roadmap/blob/responsive-images/proposals/0053-responsive-images.md).
diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index 4fc395c53da5e..728daa74bdefe 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -27,6 +27,10 @@ import {
### ``
+The `` component optimizes and transforms images.
+
+This component can also be used to create [responsive images](#responsive-image-properties) that can adjust based on the size of their container or a device screen size and resolution.
+
```astro title="src/components/MyComponent.astro"
---
// import the Image component and the image
@@ -53,7 +57,7 @@ import myImage from "../assets/my_image.png"; // Image is 1600x900
#### Image properties
-The `` component accepts all properties accepted by the HTML `![]()
` tag in addition to the properties described below.
+The `` component accepts the following listed properties and [responsive image properties](#responsive-image-properties) in addition to all properties accepted by the HTML `![]()
` tag.
##### src (required)
@@ -122,6 +126,8 @@ If an image is merely decorative (i.e. doesn't contribute to the understanding o
These properties define the dimensions to use for the image.
+When a `layout` type is set, these are automatically generated based on the image's dimensions and in most cases should not be set manually.
+
When using images in their original aspect ratio, `width` and `height` are optional. These dimensions can be automatically inferred from image files located in `src/`. For remote images, add [the `inferSize` attribute set to `true`](#infersize) on the `` or `` component or use [`inferRemoteSize()` function](#inferremotesize).
However, both of these properties are required for images stored in your `public/` folder as Astro is unable to analyze these files.
@@ -136,6 +142,8 @@ However, both of these properties are required for images stored in your `public
A list of pixel densities to generate for the image.
+The `densities` attribute is not compatible with responsive images using a `layout` property and will be ignored if set.
+
If provided, this value will be used to generate a `srcset` attribute on the `![]()
` tag. Do not provide a value for `widths` when using this value.
Densities that are equal to widths larger than the original image will be ignored to avoid upscaling the image.
@@ -181,6 +189,8 @@ A list of widths to generate for the image.
If provided, this value will be used to generate a `srcset` attribute on the `![]()
` tag. A [`sizes` property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) must also be provided.
+The `widths` and `sizes` attributes will be automatically generated for responsive images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.
+
Do not provide a value for `densities` when using this value. Only one of these two values can be used to generate a `srcset`.
Widths that are larger than the original image will be ignored to avoid upscaling the image.
@@ -222,6 +232,21 @@ import myImage from '../assets/my_image.png'; // Image is 1600x900
/>
```
+##### sizes
+
+
+
+**Type:** `string | undefined`
+
+
+
+Specifies the layout width of the image for each of a list of media conditions. Must be provided when specifying `widths`.
+
+The `widths` and `sizes` attributes will be automatically generated for responsive images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.
+
+The generated `sizes` attribute for `constrained` and `full-width` images is based on the assumption that the image is displayed close to the full width of the screen when the viewport is smaller than the image's width. If it is significantly different (e.g. if it's in a multi-column layout on small screens), you may need to adjust the `sizes` attribute manually for best results.
+
+
##### format
@@ -249,6 +274,7 @@ By default, the `` component will produce a `.webp` file.
**Type:** `boolean`
+**Default:** `false`
@@ -258,7 +284,7 @@ By default, this value is set to `false` and you must manually specify both dime
Add `inferSize` to the `` component (or `inferSize: true` to `getImage()`) to infer these values from the image content when fetched. This is helpful if you don't know the dimensions of the remote image, or if they might change:
-```astro mark="inferSize"
+```astro title="src/components/MyComponent.astro" "inferSize"
---
import { Image } from 'astro:assets';
---
@@ -267,11 +293,42 @@ import { Image } from 'astro:assets';
`inferSize` can fetch the dimensions of a [remote image from a domain that has not been authorized](/en/guides/images/#authorizing-remote-images), however the image itself will remain unprocessed.
+#### priority
+
+
+
+**Type:** `boolean`
+**Default:** `false`
+
+
+
+Allows you to automatically set the `loading`, `decoding`, and `fetchpriority` attributes to their optimal values for above-the-fold images.
+
+```astro title="src/components/MyComponent.astro" "priority"
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/my_image.png';
+---
+
+```
+
+When `priority: true` (or the shorthand syntax `priority`) is added to the `` or `` component, it will add the following attributes to instruct the browser to load the image immediately:
+
+```
+loading="eager"
+decoding="sync"
+fetchpriority="high"
+```
+
+These individual attributes can still be set manually if you need to customize them further.
+
### ``
-Use the built-in `` Astro component to display a responsive image with multiple formats and/or sizes.
+The `` component generates an optimized image with multiple formats and/or sizes.
+
+This component can also be used to create [responsive images](#responsive-image-properties) that can adjust based on the size of their container or a device screen size and resolution.
```astro title="src/pages/index.astro"
---
@@ -301,7 +358,7 @@ import myImage from "../assets/my_image.png"; // Image is 1600x900
#### Picture properties
-`` accepts all the properties of [the `` component](#image-properties), plus the following:
+`` accepts all the properties of [the `` component](#image-properties), including [responsive image properties](#responsive-image-properties), plus the following:
##### `formats`
@@ -360,6 +417,137 @@ import myImage from "../my_image.png"; // Image is 1600x900