feat: add experimental responsive images config option

packages/astro/client.d.ts

@@ -47,7 +47,11 @@ declare module 'astro:assets' {
 		getImage: (
 			options: import('./dist/assets/types.js').UnresolvedImageTransform,
 		) => Promise<import('./dist/assets/types.js').GetImageResult>;
-		imageConfig: import('./dist/types/public/config.js').AstroConfig['image'];
+		imageConfig: import('./dist/types/public/config.js').AstroConfig['image'] &
+			Exclude<
+				import('./dist/types/public/config.js').AstroConfig['experimental']['responsiveImages'],
+				boolean
+			> & { experimentalResponsiveImages: boolean };
 		getConfiguredImageService: typeof import('./dist/assets/index.js').getConfiguredImageService;
 		inferRemoteSize: typeof import('./dist/assets/utils/index.js').inferRemoteSize;
 		Image: typeof import('./components/Image.astro').default;

packages/astro/src/assets/types.ts

@@ -1,4 +1,5 @@
 import type { WithRequired } from '../type-utils.js';
+import type { ImageLayout } from '../types/public/index.js';
 import type { VALID_INPUT_FORMATS, VALID_OUTPUT_FORMATS } from './consts.js';
 import type { ImageService } from './services/service.js';
 
@@ -151,6 +152,12 @@ type ImageSharedProps<T> = T & {
 	 * ```
 	 */
 	quality?: ImageQuality;
+
+	layout?: ImageLayout;
+
+	fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | (string & {});
+
+	position?: string;
 } & (
 		| {
 				/**

packages/astro/src/assets/vite-plugin-assets.ts

@@ -114,15 +114,20 @@ export default function assets({ settings }: { settings: AstroSettings }): vite.
 				}
 			},
 			load(id) {
+				const { responsiveImages } = settings.config.experimental;
+				const experimentalConfig =
+					typeof responsiveImages === 'object' ? responsiveImages : undefined;
+				const experimentalResponsiveImages = Boolean(responsiveImages);
+
 				if (id === resolvedVirtualModuleId) {
-					return `
+					return /* ts */ `
 					export { getConfiguredImageService, isLocalService } from "astro/assets";
 					import { getImage as getImageInternal } from "astro/assets";
 					export { default as Image } from "astro/components/Image.astro";
 					export { default as Picture } from "astro/components/Picture.astro";
 					export { inferRemoteSize } from "astro/assets/utils/inferRemoteSize.js";
 
-					export const imageConfig = ${JSON.stringify(settings.config.image)};
+					export const imageConfig = ${JSON.stringify({ ...settings.config.image, experimentalResponsiveImages, ...experimentalConfig })};
 					// This is used by the @astrojs/node integration to locate images.
 					// It's unused on other platforms, but on some platforms like Netlify (and presumably also Vercel)
 					// new URL("dist/...") is interpreted by the bundler as a signal to include that directory

packages/astro/src/core/config/schema.ts

@@ -95,6 +95,7 @@ export const ASTRO_CONFIG_DEFAULTS = {
 	experimental: {
 		clientPrerender: false,
 		contentIntellisense: false,
+		responsiveImages: false,
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -525,6 +526,17 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentIntellisense),
+			responsiveImages: z
+				.union([
+					z.boolean(),
+					z.object({
+						layout: z.enum(['responsive', 'fixed', 'full-width', 'none']).optional(),
+						objectFit: z.string().optional(),
+						objectPosition: z.string().optional(),
+					}),
+				])
+				.optional()
+				.default(ASTRO_CONFIG_DEFAULTS.experimental.responsiveImages),
 		})
 		.strict(
 			`Invalid or outdated experimental feature.\nCheck for incorrect spelling or outdated Astro version.\nSee https://docs.astro.build/en/reference/configuration-reference/#experimental-flags for a list of all current experiments.`,
@@ -681,6 +693,10 @@ export function createRelativeSchema(cmd: string, fileProtocolRoot: string) {
 				config.image.endpoint.route = prependForwardSlash(config.image.endpoint.route);
 			}
 
+			if (config.experimental.responsiveImages === true) {
+				config.experimental.responsiveImages = {};
+			}
+
 			return config;
 		})
 		.refine((obj) => !obj.outDir.toString().startsWith(obj.publicDir.toString()), {

packages/astro/src/types/public/config.ts

@@ -1699,9 +1699,60 @@ export interface ViteUserConfig extends OriginalViteUserConfig {
 		 * To use this feature with the Astro VS Code extension, you must also enable the `astro.content-intellisense` option in your VS Code settings. For editors using the Astro language server directly, pass the `contentIntellisense: true` initialization parameter to enable this feature.
 		 */
 		contentIntellisense?: boolean;
+
+		/**
+		 * @docs
+		 * @name experimental.responsiveImages
+		 * @type {boolean}
+		 * @default `undefined`
+		 * @version 5.0.0
+		 * @description
+		 *
+		 * Enables and configures automatic responsive image options for images in your project. Set to `true` (for no default option passed to your images) or an object with default responsive image configuration options.
+		 *
+		 * ```js
+		 * {
+		 *  experimental: {
+		 * 		responsiveImages: {
+		 * 			layout: 'responsive',
+		 * 		},
+		 * }
+		 * ```
+		 *
+		 * Then, you can add a `layout` option to any `<Image />` component when needed to override your default configuration: `responsive`,  `fixed`, `full-width`, or `none`. This attribute is required to transform your images if `responsiveImages.layout` is not configured.  Images with a layout value of `undefined` or `none` will not be transformed.
+		 *
+		 * ```astro
+		 * ---
+		 * import { Image } from 'astro:assets';
+		 * import myImage from '../assets/my_image.png';
+		 * ---
+		 * <Image src={myImage} alt="A description of my image." layout='fixed' />
+		 * ```
+		 *
+		 */
+
+		responsiveImages?:
+			| boolean
+			| {
+					/**
+					 * @docs
+					 * @name responsiveImages.layout
+					 * @default `undefined`
+					 * @description
+					 * The default layout type for responsive images. Can be overridden by the `layout` prop on the image component.
+					 * - `responsive` - 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.
+					 */
+					layout?: ImageLayout | undefined;
+					objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down' | (string & {});
+					objectPosition?: string;
+			  };
 	};
 }
 
+export type ImageLayout = 'responsive' | 'fixed' | 'full-width' | 'none';
+
 /**
  * Resolved Astro Config
  *