Astro shouldn't allow importing Image from astro/components/Image.astro

[seasonedfish]

Body

Summary

In Astro v4, you could directly import Image from astro/components/Image.astro. In v5, this appears to still be a valid import, but it causes confusing errors.

Background & Motivation

When you start typing Image in the markup of an Astro component, VSCode offers to import Image from astro/components/Image.astro (instead of from astro:assets, the right way):

In Astro v4, this works ok, but in Astro v5, this will result in an error:

$ pnpm build

...

17:27:10 [types] Generated 714ms
17:27:10 [check] Getting diagnostics for Astro files in /var/home/fisher/Repositories/fishersun.com...
Result (23 files):
- 0 errors
- 0 warnings
- 0 hints

...

 generating static routes
Cannot access '$$Image' before initialization
  Location:
    /var/home/fisher/Repositories/fishersun.com/node_modules/.pnpm/[email protected]_@[email protected][email protected][email protected][email protected][email protected]/node_modules/astro/dist/core/build/pipeline.js:220:15
  Stack trace:
    at file:///var/home/fisher/Repositories/fishersun.com/dist/chunks/Image_BlEkfq-G.mjs:1907:10
    at async ModuleLoader.import (node:internal/modules/esm/loader:473:24)
    at async generatePages (file:///var/home/fisher/Repositories/fishersun.com/node_modules/.pnpm/[email protected]_@[email protected][email protected][email protected][email protected][email protected]/node_modules/astro/dist/core/build/generate.js:81:21)
    at async AstroBuilder.build (file:///var/home/fisher/Repositories/fishersun.com/node_modules/.pnpm/[email protected]_@[email protected][email protected][email protected][email protected][email protected]/node_modules/astro/dist/core/build/index.js:154:5)
    at async build (file:///var/home/fisher/Repositories/fishersun.com/node_modules/.pnpm/[email protected]_@[email protected][email protected][email protected][email protected][email protected]/node_modules/astro/dist/core/build/index.js:45:3)
 ELIFECYCLE  Command failed with exit code 1.

This error message is unintuitive and may result in developer frustration when upgrading from v4 to v5.

Doing a code search on the direct import statement shows hundreds of repos that make this mistake.

Goals

• improve developer experience by making it clear what the error is caused by

Proposed solutions

• disallow importing Image from astro/components/Image.astro so that it results in errors at type-check time, or
• provide a clear error message for developers that use the incorrect import at runtime

Additional info

• My blog post about my experience with this issue
• Zixian Chen's blog post referencing a similar issue, but for Picture instead

[delucis]

Thanks for the helpful feedback @seasonedfish! Would you mind posting this as a new issue in the Astro repo? I think it qualifies as a bug, so it would be nice to get it fixed!

[seasonedfish]

Yes, no problem!

[seasonedfish]

Alright, opened an issue here: withastro/astro#13142