RFC: Support `priority=true` for Images to allow preloading. #382

surjithctly · 2022-11-10T08:08:57Z

surjithctly
Nov 10, 2022

Hey this RFC is based on this issue withastro/astro#5302

The Problem

Currently, we have to preload images like this:

layout.astro

---
import { getImage } from "@astrojs/image"; 
const { src } = await getImage({
  src: "../../assets/hero.png",
  width: 800,
  height: 742,
  format: "avif",
}); 
---

<html lang="en">
  <head>
    <link rel="preload" as="image" href={src} alt="Hero" />
  </head>
  <body>

hero.astro

---
import { Image } from "@astrojs/image/components";
import heroImage from "assets/hero.png";
---

<Image  src={heroImage} alt="hero" loading="eager" format="avif" />

Result

<head>
<link rel="preload" as="image" href="/assets/hero_2ltYko.avif" alt="Hero"> 
</head>

<!-- // Notice the `hash` after each image. Its different -->

<img alt="Hero" width="800" height="742" src="/assets/hero.386919e0_1ifD2N.avif" loading="eager" decoding="async">

As you can see both of the hash after the filename is different, thus it defeats the purpose. Instead it loads two completely different image.

Proposed Solution

There should be an option called priority=true for @astro/image so Astro can automatically include that image for preloading.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-edxsa5?file=src/pages/index.astro

If anyone is willing to submit a PR, please reply.

smnbbrv · 2022-11-10T08:46:29Z

smnbbrv
Nov 10, 2022

Similar issue: #360

As to #360 (comment)

Astro’s SSR implementation streams your page’s HTML to the browser as it processes, allowing to be sent even before the rest of the page’s template has been handled on the server. This helps speed up performance for users, but means any changes to must all happen inside the element itself.

0 replies

delucis · 2022-11-10T08:48:15Z

delucis
Nov 10, 2022
Maintainer

I’m guessing the tricky part here is that because we stream our pages, by the time we reach the <Image> component, <head> has already been rendered (and, in SSR at least, sent to the user) so we can’t retroactively inject the <link rel="preload" ... > into <head>.

I guess one way is to use getImage to pass down the src to both <head> and an <img> tag. Wonder what a nice API for that would look like (or how easy it would be to make sure getImage and <Image> use the same hash — it may just be because their settings aren’t completely the same?)

8 replies

surjithctly Nov 10, 2022
Author

how do you make sure you use the exact same settings

If the hash is created based on the settings, it would output the same hash for same settings right? Similar to password?

delucis Nov 10, 2022
Maintainer

I believe so — hash of URL/file location + settings, but @tony-sull would be able to confirm.

tony-sull Nov 10, 2022
Maintainer

Our image hash is based on the props passed to getImage or the Image component, I'm guessing you there's a different hash because preload was used in the front matter but not in the actual template

I think if getImage() stripped off the preload prop it would get the same hash. The risk there is just that it'd be really easy to break and not notice it, any change to the image transformation props would need to be updated in both places

I don't know that we'd want to officially support it with a prop, but it your hash is still different when the exact same transformation props are used in both places that may be something we could fix 👍

tony-sull Nov 10, 2022
Maintainer

Actually, it probably makes sense to skip the <Image /> component all together if you use getImage 🤔

The result from getImage could be used directly on a link and img tags directly. You'd probably just have a bit of prop drilling going on, I'm guessing getImage would usually be called in the page and need to be passed to a layout component for the head and something like a <Hero /> component where the image is actually shown

surjithctly Nov 11, 2022
Author

@tony-sull Yes we could do the prop drilling, but that defeats the purpose on components. I'd love keep that in one place. I've seen people requested something similar to next/head which will push the content to the top.

But I guess the easy way is to fix the hash along with the props which can simply give a warning.

example:

<Image  src={heroImage} alt="hero" priority={true}  />
// or
<Image  src={heroImage} alt="hero" preload={true}  />

## Warning: You have added preload to /hero/<image> make sure you use the same settings in the <head> to preload it properly.

Show the warning when preload is missing or different hash?

For better developer experiences, this can be added automatically if possible or any other solution would be great.

surjithctly · 2023-10-17T09:59:40Z

surjithctly
Oct 17, 2023
Author

One year later, still looking for a proper solution.

3 replies

NicholasEwing Nov 13, 2023

In the same boat. Was hoping for a solution by now.

ps-kate Jan 27, 2024

Same here. I'm using Astro in SSG mode and considering writing an integration that would push the preloading link element to the head.

michaelowolf May 27, 2025

I looked into writing an integration/plugin that would hoist preload links to the head element recently. I ended up using middleware because Vite's transformIndexHtml hook is not supported by Astro, and I couldn't see any other way to transform Astro's generated HTML (which feels like another feature that it would be great to have support for).

I suspect using middleware is fine for SSG, but not so much for SSR (if it's ran on every request).

It looks like this:

// middleware.ts
import { defineMiddleware } from 'astro:middleware';
import { type Element, type Root } from 'hast';
import { rehype } from 'rehype';
import stringify from 'rehype-stringify';
import { visit } from 'unist-util-visit';

export const onRequest = defineMiddleware(async (_context, next) => {
  const response = await next();
  if (!response.headers.get('content-type')?.includes('text/html')) {
    return response;
  }

  const html = await response.text();
  return new Response(hoistPreloads(html), {
    status: response.status,
    headers: response.headers,
  });
});

function hoistPreloads(html: string) {
  return rehype()
    .use(rehypeHoistPreloads)
    .use(stringify)
    .processSync(html)
    .toString();
}

// Inspired by https://github.com/rehypejs/rehype-minify/tree/main/packages/rehype-css-to-top
function rehypeHoistPreloads() {
  return (tree: Root) => {
    let head: Element | undefined;
    visit(tree, { tagName: 'head' }, (node) => {
      head = node;
    });

    if (!head) {
      return;
    }

    let count = 0;
    visit(tree, { tagName: 'link' }, (node, index, parent) => {
      if (parent === head) {
        return;
      }

      const rel = Array.isArray(node.properties?.rel)
        ? node.properties?.rel
        : [node.properties?.rel];

      if (!rel.includes('preload')) {
        return;
      }

      count++;

      if (parent && index != undefined) {
        parent?.children.splice(index, 1);
      }

      head?.children.unshift(node);
    });

    if (count > 0) {
      console.info(
        `\r\nHoisted ${count} <link rel="preload"> elements to <head>`,
      );
    }
  };
}

I'm sure this isn't the perfect solution, but it does seem to work as desired - we can declare preload links alongside their corresponding images, in any Astro component, and they're moved to the header in the built page.

It would be great to see official support for this.

Princesseuh · 2023-11-14T08:52:28Z

Princesseuh
Nov 14, 2023
Maintainer

It's not super ergonomic, but in the latest versions of Astro, getImage now returns the same hash that the Image component would, so this is much easier to do manually.

Ultimately, this is still complicated to do automatically because of streaming and SSR, as is every thing that has to touch the head while being further down the page

2 replies

surjithctly Nov 14, 2023
Author

Can you share from which Astro version, it returns the same hash? I tried this last month and it did return different hash.

Princesseuh Nov 14, 2023
Maintainer

Any version post 3.5.0

RFC: Support priority=true for Images to allow preloading. #382

Uh oh!

surjithctly Nov 10, 2022

The Problem

Proposed Solution

Link to Minimal Reproducible Example

Replies: 4 comments · 13 replies

Uh oh!

smnbbrv Nov 10, 2022

Uh oh!

Uh oh!

delucis Nov 10, 2022 Maintainer

Uh oh!

surjithctly Nov 10, 2022 Author

Uh oh!

delucis Nov 10, 2022 Maintainer

Uh oh!

tony-sull Nov 10, 2022 Maintainer

Uh oh!

tony-sull Nov 10, 2022 Maintainer

Uh oh!

surjithctly Nov 11, 2022 Author

Uh oh!

surjithctly Oct 17, 2023 Author

Uh oh!

NicholasEwing Nov 13, 2023

Uh oh!

ps-kate Jan 27, 2024

Uh oh!

Uh oh!

michaelowolf May 27, 2025

Uh oh!

Uh oh!

Princesseuh Nov 14, 2023 Maintainer

Uh oh!

surjithctly Nov 14, 2023 Author

Uh oh!

Princesseuh Nov 14, 2023 Maintainer

RFC: Support `priority=true` for Images to allow preloading. #382

surjithctly
Nov 10, 2022

Replies: 4 comments 13 replies

smnbbrv
Nov 10, 2022

delucis
Nov 10, 2022
Maintainer

surjithctly Nov 10, 2022
Author

delucis Nov 10, 2022
Maintainer

tony-sull Nov 10, 2022
Maintainer

tony-sull Nov 10, 2022
Maintainer

surjithctly Nov 11, 2022
Author

surjithctly
Oct 17, 2023
Author

Princesseuh
Nov 14, 2023
Maintainer

surjithctly Nov 14, 2023
Author

Princesseuh Nov 14, 2023
Maintainer