Incorrect snippet and outdated imports in `astro:assets` docs

[ArmandPhilippot]

📚 Subject area/topic

astro/assets module

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/reference/modules/astro-assets/

📋 Description of content that is out-of-date or incorrect

I spotted two documentation issues related to assets, but I don't know yet if we should fix docs or the codebase.

1. Background prop on <Image /> https://docs.astro.build/en/reference/modules/astro-assets/#background

withastro/astro#15153 introduced a background property to control the background color used when images (e.g. png) are flattened. Using our docs code snippet we get a TypeScript error:

Type '{ src: ImageMetadata; alt: string; format: "jpeg"; background: string; }' is not assignable to type 'IntrinsicAttributes & Props'.
  Property 'background' does not exist on type 'IntrinsicAttributes & Props'.ts(2322)

Despite that, this works because <Image /> uses getImage() under the hood. But is this the intended usage? I mean, looking at the implementation PR, <Image /> were never mentioned before we update the changeset. And, currently background is only set on ImageTransform.

So, should we add background as valid prop for <Image /> (in the core repo) or should we fix the docs?

Either way, we'll need to update the docs to add ImageTransform.background in https://docs.astro.build/en/reference/modules/astro-assets/#imagetransform

2. Images utilities https://docs.astro.build/en/reference/modules/astro-assets/#imports-from-astroassetsutils

• matchHostname, matchPathname, matchPort, and matchProtocol were removed in fix(astro): remove unused re-exports causing Vite build warning astro#16197

• emitImageMetadata, propsToFilename, and hashTransform were removed in https://github.com/withastro/astro/pull/14306/changes#diff-d48e632552d390dcbbb96a1bd4d7989897c469b75379973c0d721815fd00c7d8
  Then, propsToFilename and hashTransform were added to astro/assets in fix: update Cloudflare adapter's default image service astro#15435

This is a v6 breaking change and the upgrade guide doesn't mention it! Actually, this is even worse: we recommend using emitImageMetadata instead of emitEsmImage but this helper is no longer available, see https://docs.astro.build/en/guides/upgrade-to/v6/#removed-emitesmimage.

Is the breaking change intentional? Those were documented in the Image Service API before moving to that page (see #11158 and #11194).

If this is intentional, we should we remove them from the docs and update the v6 upgrade guide to mention the removal. Otherwise, we'll have to add them back in the core repo.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

For the background issue:

https://stackblitz.com/edit/astro-image-background-prop?file=src%2Fcomponents%2FMyComponent.astro&on=stackblitz

Run astro check or download the repro locally to see the TypeScript error in your editor.

[delucis]

So, should we add background as valid prop for <Image /> (in the core repo) or should we fix the docs?

If it works, I’d assume it should be correctly typed in the core repo? In general Image and getImage should mostly work identically, so there’d need to be a very good reason to only support this in getImage. And the original changeset is pretty explict: “Adds a new background property to the <Image /> component.”

---

Re: the second one – it sounds like it may have been unintentional? But I’m not familiar enough to say for sure. I’m guessing that the PR says “unused exports” and @matthewp took the PR author at their word when in fact these were public APIs.

[ArmandPhilippot]

the original changeset is pretty explict

Yeah, after Sarah's suggestion. But originally it was:

Add background in ImageTransform, to allow flattening images with the given background color. This is especially useful when the requested output format doesn't support an alpha channel, e.g. jpeg.

There was no mention of <Image /> at all, hence my doubt. And, maybe that's why the changes do not include <Image /> types (ie. the PR was designed for getImage() only). But, I also think it makes sense for this prop to work with the <Image /> component.

And yes, the second issue is trickier, because it involves three unrelated PRs. In emitImageMetadata case, this wasn't a bug fix but this was removed in the Environment API refactoring. So, I don't know if it was intentional or an oversight...

I was planning to ask on Discord this afternoon but since you've pinged Matthew, we should probably also ping @ematipico, who might have more context on the changes made for the Environment API. (t's been a while though... 😅 ).

[delucis]

There was no mention of <Image /> at all, hence my doubt.

I suspect it’s just a case of a dev describing the code they changed instead of thinking from a user POV. And if they did accept Sarah’s improvement, I guess they also thought it made sense without thinking to check the types.

[ematipico]

I think background should be added to Image component too, so it was an oversight on our part.

---

emitImageMetadata is in the source code, what do you mean with it's not there anymore? You mean you can't import it from astro/assets/utils?

EDIT: it's possible it was an oversight on our part when we moved things around for the environment APIs. That's an utility that uses Node.js, so we couldn't import it lightly

[ematipico]

We now have imageMetadata, which contains mostly all the information emitted by emitImageMetadata, minus 'src' and 'fsPath'

[ArmandPhilippot]

emitImageMetadata is in the source code, what do you mean with it's not there anymore? You mean you can't import it from astro/assets/utils?

Yes, exactly:

And this is the same error for every imports with red squiggles!

So, we need to figure which imports should still be public and which one requires a docs update:

• matchHostname
• matchPathname
• matchPort
• matchProtocol
• emitImageMetadata
• propsToFilename (moved, we can update docs if it easier)
• hashTransform (moved, we can update docs if it easier)

We now have imageMetadata, which contains mostly all the information emitted by emitImageMetadata, minus 'src' and 'fsPath'

Yeah I saw that. It seems a bit redundant but maybe there are use cases for both... That's also why I was wondering if this was intentional are not.

[ematipico]

I believe we can fix the majority of them. Some of them have been moved around in internal-helpers (probably a mistake), some others still exist but they aren't exported anymore. Only emitImageMetadata should be "removed" in favour of imageMetadata. I'll continue the discussion on Discord, since it might require some changes

[ArmandPhilippot]

Thanks! In the meantime, since we seem to agree on that, I opened an issue in the core repo for background: withastro/astro#17471

[matthewp]

Yeah, <Image /> and getImage should match signatures, that one is easy.

As far as astro/assets/utils, I'm not sure. I think anything that we explicitly made public, there's a minor release changeset for, then those should of course be public and documented. Anything else, that we put there by mistake, because it was needed inside Astro, and that was the convenient place to export from, without realizing the implications, those should not be public. I suspect the match* ones fall into the latter, but someone should investigate the changesets to see.

[ArmandPhilippot]

Sorry, I had completely forgotten about the last comment... So, I checked and most of them are associated with a patch not a minor.

There are a lot of links; I hope this is still readable. I also checked the others in case we want to do some clean up (I putted them in a <details /> below the list).

• isRemoteAllowed, matchHostname, matchPathname, matchPattern, matchPort, matchProtocol:
  • exported from astro/assets/utils since refactor(assets): Move things around to avoid importing image service unnecessarily astro#9409 (no changeset)
  • removed in feat: Pass remote Markdown images through image service astro#13254 (minor, no dedicated changeset)
  • added back in fix(assets): export again asset utilities astro#13336 (patch) because Erika said in Astro 5.4 breaks custom Image Services astro#13335 (comment) that they were "purposely exported for other services to use"
  • documented since docs: document asset utilities astro#13355 (patch) / Docs PR: docs: document asset utilities astro#13355
  • partially removed in fix(astro): remove unused re-exports causing Vite build warning astro#16197 (patch)
  • now... should we add them back? I suppose Erika's comment is still valid, even though I don't think anyone complained.
• emitImageMetadata:
  • exported from astro/assets/utils as replacement of emitESMImage since chore: deprecate emitESMImage function astro#13589 (patch) / Docs PR: feat: document emitImageMetadata, deprecate emitESMImage #11401 (FWIW, emitESMImage was exported since Fix/markdoc assets astro#7706)
  • removed in Environment API astro#14306 (major, no dedicated changeset)
  • according to Ema, we don't need to add it back because we have imageMetadata: if we do that, we should add something in the v6 upgrade guide
• propsToFilename and hashTransform:
  • exported from astro/assets/utils since Misc improvements for astro:assets astro#7759 (patch, no dedicated changeset)
  • documented since docs: document utility functions astro#13367 (patch) / Docs PR: feat(assets): document more utilities #11194
  • removed in Environment API astro#14306 (major, no dedicated changeset)
  • now... should we add them back? I can see the cloudflare adapter imports them from the new location, so I guess they could be helpful for third-party adapters/image services?

History for the other exports

• emitClientAsset:
  • exported from astro/assets/utils since fix: prevent .sql files from being moved to client assets during SSR build astro#15345 (minor) / Docs PR: Document new emitClientAsset function #13223
• isESMImportedImage and isRemoteImage:
  • exported from astro/assets/utils since refactor(assets): Move things around to avoid importing image service unnecessarily astro#9409 (no changeset)
  • documented since docs: document utility functions astro#13367 (patch) / Docs PR: feat(assets): document more utilities #11194
• resolveSrc:
  • documented since docs: document utility functions astro#13367 (patch) / Docs PR: feat(assets): document more utilities #11194
  • exported from astro/assets/utils since fix: add missing export for a documented image service utility astro#14276 (patch)
• imageMetadata and getOrigQueryParams:
  • exported from astro/assets/utils since Misc improvements for astro:assets astro#7759 (patch, no dedicated changeset)
  • documented since docs: document utility functions astro#13367 (patch) / Docs PR: feat(assets): document more utilities #11194
• inferRemoteSize:
  • exported from astro/assets/utils since Expose inferRemoteSize function astro#11098 (minor)
  • documented since docs: document utility functions astro#13367 (patch) / Docs PR: feat(assets): document more utilities #11194