getImage() — astro Function Reference

Architecture documentation for the getImage() function in internal.ts from the astro codebase.

Function typescript CoreAstro RenderingEngine calls 1

Entity Profile

CoreAstro→ RenderingEngine→ getImage() — astro Function Reference

Dependency Diagram

graph TD
  84967c2c_7ba2_2d7e_57a8_a20740526215["getImage()"]
  aac8b1fe_d242_0071_1169_4222f10fb7b6["internal.ts"]
  84967c2c_7ba2_2d7e_57a8_a20740526215 -->|defined in| aac8b1fe_d242_0071_1169_4222f10fb7b6
  91cd6b7a_b120_cd6c_671d_779ee58b17f4["getConfiguredImageService()"]
  84967c2c_7ba2_2d7e_57a8_a20740526215 -->|calls| 91cd6b7a_b120_cd6c_671d_779ee58b17f4
  style 84967c2c_7ba2_2d7e_57a8_a20740526215 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/astro/src/assets/internal.ts lines 44–253

export async function getImage(
	options: UnresolvedImageTransform,
	imageConfig: AstroConfig['image'] & AstroAdapterClientConfig,
): Promise<GetImageResult> {
	if (!options || typeof options !== 'object') {
		throw new AstroError({
			...AstroErrorData.ExpectedImageOptions,
			message: AstroErrorData.ExpectedImageOptions.message(JSON.stringify(options)),
		});
	}
	if (typeof options.src === 'undefined') {
		throw new AstroError({
			...AstroErrorData.ExpectedImage,
			message: AstroErrorData.ExpectedImage.message(
				options.src,
				'undefined',
				JSON.stringify(options),
			),
		});
	}

	if (isImageMetadata(options)) {
		throw new AstroError(AstroErrorData.ExpectedNotESMImage);
	}

	const service = await getConfiguredImageService();

	// If the user inlined an import, something fairly common especially in MDX, or passed a function that returns an Image, await it for them
	const resolvedOptions: ImageTransform = {
		...options,
		src: await resolveSrc(options.src),
	};

	let originalWidth: number | undefined;
	let originalHeight: number | undefined;

	// Infer size for remote images if inferSize is true
	if (resolvedOptions.inferSize) {
		delete resolvedOptions.inferSize; // Delete so it doesn't end up in the attributes

		if (isRemoteImage(resolvedOptions.src) && isRemotePath(resolvedOptions.src)) {
			const getRemoteSize = (url: string) =>
				service.getRemoteSize?.(url, imageConfig) ?? inferRemoteSize(url);
			const result = await getRemoteSize(resolvedOptions.src); // Directly probe the image URL
			resolvedOptions.width ??= result.width;
			resolvedOptions.height ??= result.height;
			originalWidth = result.width;
			originalHeight = result.height;
		}
	}

	const originalFilePath = isESMImportedImage(resolvedOptions.src)
		? resolvedOptions.src.fsPath
		: undefined; // Only set for ESM imports, where we do have a file path

	// Clone the `src` object if it's an ESM import so that we don't refer to any properties of the original object
	// Causing our generate step to think the image is used outside of the image optimization pipeline
	const clonedSrc = isESMImportedImage(resolvedOptions.src)
		? // @ts-expect-error - clone is a private, hidden prop
			(resolvedOptions.src.clone ?? resolvedOptions.src)
		: resolvedOptions.src;

	if (isESMImportedImage(clonedSrc)) {
		originalWidth = clonedSrc.width;
		originalHeight = clonedSrc.height;
	}

	if (originalWidth && originalHeight) {
		// Calculate any missing dimensions from the aspect ratio, if available
		const aspectRatio = originalWidth / originalHeight;
		if (resolvedOptions.height && !resolvedOptions.width) {
			resolvedOptions.width = Math.round(resolvedOptions.height * aspectRatio);
		} else if (resolvedOptions.width && !resolvedOptions.height) {
			resolvedOptions.height = Math.round(resolvedOptions.width / aspectRatio);
		} else if (!resolvedOptions.width && !resolvedOptions.height) {
			resolvedOptions.width = originalWidth;
			resolvedOptions.height = originalHeight;
		}
	}
	resolvedOptions.src = clonedSrc;