Replacing Astro Image for a Documentation Site

I started a docs site with Astro’s Image component because the defaults are good and the integration with Sharp is pre-built. After a few months of running at scale, I removed it.

The problems were not Astro’s fault, exactly. They were the consequence of an abstraction that has to serve every kind of content site, applied to one that has very specific needs. Inferring sizes from remote images was the slowest step in the build. Tables that contained images fought the wrapper layout. Reintroducing automatic width and height to make table cells render correctly was a recurring fix. The wrapper added padding and aspect-ratio behavior that made sense for blog hero images and made no sense for a small inline diagram.

The Custom Wrapper

The replacement was a thin component that took a source path, rendered an image tag, and got out of the way. For local images, dimensions came from Sharp’s metadata function, called once at build time. For remote images, the component skipped the inference entirely and let the browser handle it, with explicit loading, decoding, and fetch priority attributes set so above-the-fold images still loaded fast.

The whole thing was smaller than the configuration block I had been writing for Astro Image. It covered the cases the docs actually had, and stopped covering the ones they did not.

When Generic Costs More Than Specific

There is a moment with every shared abstraction where it stops paying for itself. The clue is that you start fighting it, applying overrides, working around its assumptions, importing it conditionally. Each override is the abstraction telling you it is not a fit for your case. After the third or fourth override, the cheapest move is usually to write the small specific version yourself.

I am not against Astro Image. For a content site with a uniform shape, it is the right default. For a docs site with mixed content, table-embedded diagrams, remote screenshots, and dozens of inline icons, the cost of bending the abstraction was greater than the cost of replacing it.

What I Learned

The strength of an abstraction is that it covers many cases at once. The weakness is that it covers them all the same way. When the variance in your content is bigger than the variance the abstraction was designed for, the right move is not to fight the abstraction. It is to admit it does not fit and write the small thing that does.