Skip to content

Latest commit

 

History

History
86 lines (65 loc) · 4.38 KB

imports.md

File metadata and controls

86 lines (65 loc) · 4.38 KB

Imports

Astro docs: Imports

Astro lets a component import almost anything Vite can resolve: another component, an image, JSON, CSS, a npm package, ?raw and ?url variants, import.meta.glob(). A .razor file has no ESM imports of its own, because it is compiled by the Razor compiler rather than by Vite. What stands in for them is Astro.Import, and the difference is not only spelling — it decides which of Astro's import types have a C# meaning at all.

The rule

Astro.Import(path) does not hand C# a value. The path is a compile-time literal, so the build reads it out of the call, generates a real import in the module it compiles for that file, and hands back a stand-in. The stand-in is substituted for the real binding after the render, on its way into the output or into a component's props.

So an import is useful exactly when the thing being imported is for Astro, and useless when the value is meant to be read by your C#.

@* For Astro: the ImageMetadata reaches <Image>, which is Astro's own component *@
<Image Src='Astro.Import("../assets/hero.png")' Alt="A hero" Width="400" />

@* For Astro: the component is rendered by Astro and spliced into this page *@
@Astro.Component(Astro.Import("./Badge.astro"), new { label = "new" })
@* Not this. There is no value here to read -- the stand-in is not the JSON. *@
@{ var data = Astro.Import("./data.json"); }
<p>@data.Something</p>   @* does not compile, and would not mean anything if it did *@

Read data in C# with C#: File.ReadAllText, System.Text.Json, an injected service, a NuGet package. See Data fetching.

What each of Astro's import types does here

Astro In C#
Another .astro component Astro.Import, then Astro.Component — Components
A framework component (island) Astro.Import(..., client: "load") — Frameworks
Images and assets Astro.Import into <Image> / <Picture>, or a plain string Src for public/ — Images
CSS, Sass, Tailwind [AstroStylesheet("./card.scss")] — Styles
astro:* modules [AstroModule] plus Astro.Module(...) — Runtime API modules
Another .razor component Not an import at all: they compile together, so it is reached by namespace
npm packages, .ts, .js Only as something handed to Astro. A .razor file cannot call into JavaScript; use a NuGet package, or an endpoint
JSON No C# meaning — the stand-in is not the parsed object. Read the file in C#
?raw, ?url Untested. ?url may work where a plain string is wanted; ?raw has the JSON problem above
import.meta.glob() No equivalent. Enumerate with System.IO, or use a content collection
Node builtins (node:fs) Not applicable — the BCL is already there
WASM Not applicable

Aliases

Whatever Vite resolves, Astro.Import resolves, because the generated import is an ordinary one. A tsconfig.json path alias works:

{ "compilerOptions": { "paths": { "@components/*": ["./src/components/*"] } } }
@Astro.Component(Astro.Import("@components/Badge.astro"), new { label = "new" })

A relative path is resolved against the .razor file, since the generated module sits beside it.

Limitations

The path has to be a literal. The build reads it out of the call to generate the import, and Vite resolves imports statically — a path built at runtime cannot be imported at all, and the build says so rather than failing later.

An import of a file has to be written in the .razor file that .astro imports, not in a nested component: the generated import goes into that file's compiled module, and a nested component has none of its own in the page's graph. An import of a module is registered project-wide instead, which is why <Image> works at any depth.

A stand-in cannot be stored, measured or passed on as a prop. It is not the value; it stands in for one until the render is over. One that survives to the output fails the build rather than shipping as visible gibberish.

Nothing here reaches the browser as C#. See Islands architecture.