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.
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.
| 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 |
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.
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.