C# lives in src/, next to the .astro files. There is no separate .NET project to maintain and no
directory to keep in sync.
src/
components/Card.razor a C# component
pages/index.astro an ordinary Astro page
pages/hello.razor a C# page (serves /hello)
lib/Blog.cs a content loader
lib/Actions.cs actions
lib/Api.cs endpoints
lib/Mw.cs middleware
lib/Startup.cs service registration
content.config.ts build-time collections
live.config.ts live collections
.astrosharp/ generated; do not edit or commit
Components and pages are .razor files, and their location matters: a file under src/pages
becomes a route by its name, exactly as .astro and .mdx do. Anywhere else it is a component.
Everything else is found by reflection, so the .cs files can be organised however you like.
A loader is any class implementing IContentLoader; an action any class implementing
IAstroAction<,>; middleware any class implementing IAstroMiddleware. Nothing has to be
registered, and no folder is significant.
The one exception is endpoints, where the file path is the route — src/pages/api/status.json.cs
serves /api/status.json. An endpoint outside src/pages names its own route with
[AstroEndpoint("/api/status.json")]. See Endpoints.
Route file names stay lowercase and route-shaped; AstroSharp synthesizes a valid PascalCase Razor
class name internally, so about-us.razor and [id].razor are both fine.
Components are namespaced by their folder, so components/Card.razor and ui/Card.razor do not
collide. A file that declares its own @namespace is honoured.
The integration generates .astrosharp/AstroSharpApp.csproj on every run: it globs your src/,
references the NuGet packages you declared, and carries the build output.
Never edit it, and do not commit .astrosharp/. Add it to .gitignore. It is regenerated from
scratch on a cold start.
.razor only. .cshtml is not supported, and neither is any Astro-shaped C# component syntax —
there is no --- fence and no {expression}. See Components.
A .razor file has no ESM imports of its own, because it is compiled by the Razor compiler
rather than by Vite. What it has instead is Astro.Import, a call
the build reads the path out of and turns into a real import — so an .astro component, an image or
one of Astro's own modules is reached the way it would be in .astro, one line, written where it is
used. Stylesheets are declared with [AstroStylesheet].
A C# component composes by namespace, not by path. Astro.Import reaches the files Vite owns;
another .razor component is reached by its folder-derived namespace, since both are compiled
together by Roslyn and neither is a module the other could import.