CSS background images are a blind spot in Astro's image + CSP story

[osiegmar]

Summary

There is no CSP-compatible way to use Astro's image optimization pipeline for CSS background-image. The two delivered roadmap efforts — the core image story and CSP support — work well individually but don't cover this intersection.

Background & Motivation

CSS background-image is widely used for decorative visuals like hero sections, page headers, and banners. Sites that care about performance want format negotiation (AVIF → WebP → JPEG via image-set()). Sites that care about security want strict CSP. Right now you can't have both without building your own pipeline outside of Astro.

Every available path hits a wall:

1. Reference assets in CSS url()

.hero { background-image: url('@assets/images/bg.png'); }

Astro/Vite won't resolve src/assets/ paths in CSS, so images never enter the optimization pipeline. (#9633, closed as a Vite limitation)

2. define:vars with getImage()

---
const img = await getImage({ src: bgSrc, format: 'avif' });
---
<style define:vars={{ bg: `url(${img.src})` }}>
  .hero { background-image: var(--bg); }
</style>

define:vars injects inline style attributes on every element in the component (#7328, closed as intentional design, behavior unchanged in Astro 6), which violates strict CSP. Adding 'unsafe-inline' to style-src doesn't help either, because Astro's CSP hash injection causes browsers to ignore it (#14798).

Goals

• Allow getImage() results to be used as CSS background-image values without violating strict CSP
• Support multi-format negotiation (image-set() with AVIF/WebP/JPEG fallbacks) for background images
• Avoid requiring manual CSS string building, SHA-256 hashing, and CSP hash registration

Example

Today, we ship this workaround in production — it works, but it's entirely outside Astro's style system:

async function buildCss(name: string, src: ImageMetadata): Promise<string> {
  const [avif, webp, jpg] = await Promise.all([
    getImage({ src, format: "avif" }),
    getImage({ src, format: "webp" }),
    getImage({ src, format: "jpg" }),
  ]);
  return `.${name}{background-image:url(${jpg.src});background-image:image-set(url(${avif.src}) type("image/avif"),url(${webp.src}) type("image/webp"),url(${jpg.src}) type("image/jpeg"))}`;
}

export async function registerBgCspHashes(csp) {
  for (const css of allCssStrings) {
    const hash = `sha256-${createHash("sha256").update(css).digest("base64")}`;
    csp.insertStyleHash(hash);
  }
}

This requires hand-building CSS as strings, manually SHA-256 hashing them, registering hashes with Astro.csp in the layout frontmatter (which must execute before child components, since child frontmatter runs after the CSP <meta> tag is emitted), and injecting via <style set:html={css}></style>.

An alternative workaround is replacing background-image with a <Picture> using object-fit: cover and absolute positioning. This avoids the problem entirely but only works for simple cover images — sites that need background-repeat, background-blend-mode, or multiple layered backgrounds still have no CSP-compatible path.