Images and Assets

Purpose and Scope

Astro’s image and asset system gives authors a high-level way to display optimized media while still fitting the project’s build and deployment model. In user code, the most visible surface is the astro:assets virtual module, which official documentation describes as exporting components and helpers such as Image, Picture, Font, getImage, inferRemoteSize, getConfiguredImageService, imageConfig, fontData, and experimental_getFontFileURL. The reader problem this page solves is how to connect that public authoring API to the lower-level repository evidence for asset URL construction, deterministic file identity, and build packaging.

Sources: packages/astro/src/assets/fonts/infra/build-url-resolver.ts, packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts

For application authors, the primary distinction is between source-managed assets and public URL assets. Local images under src/ are imported so Astro and Vite can produce metadata, optimize output, and enforce useful attributes. Files served from public/ are addressed by URL path instead. Dynamic image selection follows the same model: official recipes use Vite’s import.meta.glob with ImageMetadata so a component can map runtime props to known build-time image modules rather than constructing unchecked filesystem paths. That pattern preserves optimization while still allowing data-driven card grids, author avatars, and similar content interfaces.

Core Primitives

The Image component is the everyday primitive for a single optimized image. It accepts a required src that can be image metadata, a string URL, or a promise resolving to an imported image module, and official docs require meaningful alt text for accessibility. Picture extends the same concept when a page needs multiple formats or responsive sources. getImage is the programmatic helper for code paths that need a generated image result outside direct component markup, while inferRemoteSize supports remote image workflows where dimensions are not already known from a local import.

Fonts belong to the same broad asset family because they must be emitted with stable identifiers, resolved into URLs, and tracked for security policy decisions. The repository’s font build helpers show that Astro does not treat emitted files as arbitrary strings. BuildFontFileIdGenerator receives a hasher and a content resolver, resolves the original font URL to content, hashes that content, and appends the font type as the extension. That means the emitted file identity is derived from content and type rather than from only the author’s original path.

Sources: packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts

Image services are the extension point behind the public components. Official docs define two broad service categories: local services, which transform assets at build time for static output or at runtime in development and on-demand rendering, and external services, which generate URLs for platforms such as Cloudinary, ImageKit, Vercel, or another remote image transformation server. Both service styles can validate options and set HTML attributes; local services also participate in endpoint-style URL parsing and transformation. This is why Astro’s asset API feels component-first while still supporting deployment-specific media infrastructure.

Relevant Source Files

• .changeset/sharp-bags-build.md — Records a build-time failure-surfacing fix for Cloudflare workerd prerendering, useful context for asset and route rendering reliability during astro build.
• configs/tsconfig.build.json — Defines the shared package build TypeScript configuration, including rootDir, outDir, build info cache location, and source inclusion.
• packages/astro-prism/tsconfig.build.json — Shows an Astro package extending the shared build configuration while including package source and virtual declarations.
• packages/astro-rss/tsconfig.build.json — Shows another published package extending the shared build configuration directly.
• packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts — Implements build-time font file ID generation from resolved content and font type.
• packages/astro/src/assets/fonts/infra/build-url-resolver.ts — Implements build-time URL resolution for emitted font assets, including base paths, asset prefixes, search parameters, URL tracking, and CSP resource tracking.

System-to-Code Mapping

The asset system has two layers that are useful to keep separate. The author-facing layer is expressed through astro:assets imports in .astro components and supporting TypeScript types such as ImageMetadata. The implementation-facing layer resolves asset identities and URLs in a way that remains stable across builds and compatible with adapters. The supplied font source files are examples of that lower layer: one class generates deterministic emitted file IDs, and the other turns emitted IDs into final URLs while remembering the resources that must be permitted by content security policy.

Sources: packages/astro/src/assets/fonts/infra/build-url-resolver.ts, packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts

BuildUrlResolver is especially important for deployment correctness. It accepts a configured base, an assetsPrefix, and URLSearchParams. When a prefix exists, the resolver chooses a prefix based on the file extension and records that prefix as a CSP resource; otherwise it records 'self' and prepends a forward slash to the joined base and file ID. It then creates a placeholder URL, copies configured search parameters into it, stringifies the result, and stores the final URL. This sequence lets adapter-level features such as tracking parameters coexist with generated asset URLs.

Sources: packages/astro/src/assets/fonts/infra/build-url-resolver.ts

The build configuration files explain how this infrastructure is packaged. The shared build config extends the repository’s base TypeScript settings, constrains compilation to each package’s src directory, emits to dist, and writes TypeScript build information into a cache directory under dist/._cache/ts_build. Package-level configs such as packages/astro-prism/tsconfig.build.json and packages/astro-rss/tsconfig.build.json extend that shared config, which keeps published package builds consistent even when the package’s runtime domain is not image optimization.

Sources: configs/tsconfig.build.json, packages/astro-prism/tsconfig.build.json, packages/astro-rss/tsconfig.build.json

Execution Flow

A typical local-image flow starts in a component. The author imports Image from astro:assets, imports a local file from src/, and renders <Image src={myImage} alt="..." />. At build time, Vite can statically understand the image import and Astro can transform that metadata into output markup with width, height, loading, decoding, and final source information. When the chosen image is data-driven, official docs recommend using import.meta.glob<{ default: ImageMetadata }> over the directory and then indexing that object by a known path supplied through props.

---
import type { ImageMetadata } from 'astro';
import { Image } from 'astro:assets';
 
const { imagePath, altText } = Astro.props;
const images = import.meta.glob<{ default: ImageMetadata }>('/src/assets/*.{jpeg,jpg,png,gif}');
const image = images[imagePath];
---
 
{image && <Image src={image()} alt={altText} />}

For emitted font files, the flow is visible in the supplied implementation classes. A source URL is resolved to file content, that content is hashed, and the font type becomes the extension of the emitted file ID. Later, URL resolution combines that ID with project base and asset prefix settings. The resolver’s stored urls can describe which asset URLs were produced, and cspResources records whether those URLs require 'self' or a configured external asset prefix in security policy output.

Sources: packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts, packages/astro/src/assets/fonts/infra/build-url-resolver.ts

Build and prerender reliability matter because asset URLs are often produced during the same rendering pass that emits HTML. The Cloudflare changeset included in the evidence records a fix where prerender errors thrown inside workerd were no longer silently swallowed; response bodies are buffered so streaming errors become build failures with clear messages. Although that note is adapter-specific, it reinforces the expected behavior for build output: truncated HTML or hidden render errors should not be accepted as successful production artifacts.

Sources: .changeset/sharp-bags-build.md

Compact Reference

Use astro:assets when an Astro component or server-side module needs Astro-managed media behavior rather than a plain HTML tag. The main public imports described by the official docs are Image, Picture, Font, getImage, inferRemoteSize, getConfiguredImageService, imageConfig, fontData, and experimental_getFontFileURL. Use imported local image metadata for files in src/; use a root-relative URL string for files intentionally placed in public/; use import.meta.glob when the component must select from a known set of local images dynamically.

Image service authors should think in terms of validation, URL production, transformation, and HTML attributes. External services primarily return a remote URL from getURL(). Local services additionally transform image data and parse endpoint URLs so development and on-demand rendering can request generated variants. That contract is separate from the font helpers shown in this page, but the same design principle applies: public APIs stay declarative while implementation code centralizes emitted IDs, URL construction, and deployment-aware metadata.

Next Steps

If you are building an Astro site, start with Image and Picture before reaching for a custom image service. If your page selects images from content data, use the dynamic import recipe rather than manually concatenating paths. If you are extending Astro or investigating generated output, read the font ID and URL resolver implementations together: one decides what the emitted asset is called, and the other decides how that emitted asset is referenced from HTML, CSS, or runtime metadata.