Astro shouldn't allow importing Image or Picture from astro/components/

[seasonedfish]

Originally discussed in withastro/roadmap#1114

Astro Info

Astro                    v5.2.5
Node                     v20.17.0
System                   Linux (x64)
Package Manager          pnpm
Output                   static
Adapter                  none
Integrations             @astrojs/tailwind
                         @astrojs/sitemap
                         astro-expressive-code

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

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 when the user runs astro build. Interestingly, it seems that the project must include a content collection and a dynamic route for the error to occur.

$ 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/astro@5.2.5_@types+node@20.14.10_jiti@1.21.6_rollup@4.34.2_typescript@5.5.3_yaml@2.7.0/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/astro@5.2.5_@types+node@20.14.10_jiti@1.21.6_rollup@4.34.2_typescript@5.5.3_yaml@2.7.0/node_modules/astro/dist/core/build/generate.js:81:21)
    at async AstroBuilder.build (file:///var/home/fisher/Repositories/fishersun.com/node_modules/.pnpm/astro@5.2.5_@types+node@20.14.10_jiti@1.21.6_rollup@4.34.2_typescript@5.5.3_yaml@2.7.0/node_modules/astro/dist/core/build/index.js:154:5)
    at async build (file:///var/home/fisher/Repositories/fishersun.com/node_modules/.pnpm/astro@5.2.5_@types+node@20.14.10_jiti@1.21.6_rollup@4.34.2_typescript@5.5.3_yaml@2.7.0/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.

The same error occurs for Picture.

Additional info

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

What's the expected result?

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

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-cfi9o9ng?file=src%2Fpages%2Findex.astro

Run npm run build to see the error.

Participation

• I am willing to submit a pull request for this issue.

Possibly, with some guidance! I'm new to the project.

[florian-lefebvre]

I think it should work? It's probably a bug