docs: Add guidance regarding using getImage on the client (#13354)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: Princesseuh

src/content/docs/en/guides/images.mdx

@@ -633,6 +633,24 @@ const allBlogPosts = await getCollection("blog");
 
 The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes). When you need options that the `<Picture>` and `<Image>` components do not currently support, you can use the `getImage()` function to create your own custom `<Image />` component.
 
+`getImage()` can only be used on the server. If you need to use the resulting image URL on the client (e.g. in a client-side script or framework component), call `getImage()` inside the frontmatter and pass the resulting `src` to the client:
+
+```astro title="src/components/ClientImage.astro"
+---
+import { getImage } from "astro:assets";
+import myBackground from "../background.png";
+
+const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
+---
+
+<div id="background" data-src={optimizedBackground.src}></div>
+
+<script>
+  const src = document.getElementById("background").dataset.src;
+  // use src client-side as needed
+</script>
+```
+
 <ReadMore>See more in the [`getImage()` reference](/en/reference/modules/astro-assets/#getimage).</ReadMore>
 
 <RecipeLinks slugs={["en/recipes/build-custom-img-component" ]}/>

src/content/docs/en/guides/upgrade-to/v6.mdx

@@ -1430,6 +1430,36 @@ If you were previously relying on the fact that the image service would automati
 
 <ReadMore>Learn more about [the `format` image property](/en/reference/modules/astro-assets/#format)</ReadMore>
 
+### Changed: `getImage()` throws when called on the client
+
+<SourcePR number="15800" title="feat: disallow getImage on the client" />
+
+In Astro 5.x, calling `getImage()` from `astro:assets` on the client would silently fail or produce incorrect results.
+
+Astro 6.0 throws a runtime error when `getImage()` is called on the client.
+
+#### What should I do?
+
+Call `getImage()` on the server and pass the resulting `src` to the client instead:
+
+```astro title="src/components/ClientImage.astro" {5, 8, 11}
+---
+import { getImage } from "astro:assets";
+import myBackground from "../background.png";
+
+const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
+---
+
+<div id="background" data-src={optimizedBackground.src}></div>
+
+<script>
+  const src = document.getElementById("background").dataset.src;
+  // use src client-side as needed
+</script>
+```
+
+<ReadMore>See [generating images with `getImage()`](/en/guides/images/#generating-images-with-getimage) for a full example.</ReadMore>
+
 ### Changed: Markdown heading ID generation
 
 <SourcePR number="14494" title="feat!: stabilize experimental.headingIdCompat"/>

src/content/docs/en/reference/modules/astro-assets.mdx

@@ -638,7 +638,9 @@ Variable weight font files will be preloaded if any weight within its range is r
 </p>
 
 :::caution
-`getImage()` relies on server-only APIs and breaks the build when used on the client.
+`getImage()` relies on server-only APIs and will throw an error on the client. 
+
+If you need the resulting image URL client-side, you can [pass the `src` from a server-rendered `getImage()` call to the client](/en/guides/images/#generating-images-with-getimage).
 :::
 
 The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `<Image />` component.