Atoll

A .NET-native framework inspired by Astro. Atoll brings server-first HTML rendering, islands architecture, content collections, and static site generation to the .NET ecosystem.

Atoll applies Astro's core philosophy to .NET: ship zero JavaScript by default, then selectively hydrate interactive components ("islands") on the client. Pages and components render server-side as plain HTML. Only the parts that need interactivity load JavaScript — and only when they need to.

Atoll is organized into focused NuGet packages:

HTTP Request
  → ASP.NET Core pipeline
    → AtollMiddleware
      → RouteMatcher (pattern matching)
        → IAtollPage → LayoutResolver → PageRenderer → HTML response
        → IAtollEndpoint → EndpointDispatcher → JSON/text/redirect response

Every component extends AtollComponent and implements RenderCoreAsync. The rendering API is intentionally simple:

• WriteHtml(string) — write trusted HTML directly to the output
• WriteText(string) — write text that is automatically HTML-escaped
• RenderSlotAsync() — render child content (the default slot)
• RenderSlotAsync(name) — render a named slot
• RenderAsync(fragment) — render a RenderFragment (for composing child components)

Components are rendered top-down, synchronously or asynchronously, producing a stream of HTML chunks.

Full guides and API details live in docs/:

The repository includes three complete sample sites in samples/:

• Blog — Layouts, content collections with frontmatter, tag filtering, Markdown rendering, interactive islands (theme toggle, search)
• Portfolio — Hero sections, project cards, [ClientLoad] / [ClientVisible] / [ClientMedia] islands, responsive layout
• Articles — Article series with navigation, documentation-style theme

A typical Atoll project:

MySite/
├── Components/          # Reusable UI components
├── Content/             # Markdown content collections
│   └── blog/
├── Islands/             # Interactive client-side islands
├── Layouts/             # Page layout wrappers
├── Pages/               # Routable page components
├── BlogPostSchema.cs    # Content collection schema
└── MySite.csproj

Install packages from NuGet. Most sites need the core package plus a theme:

# Core + middleware (for dev server and ASP.NET Core hosting)
dotnet add package Atoll.Middleware

# Documentation theme
dotnet add package Atoll.Lagoon

# Blog/articles theme
dotnet add package Atoll.Reef

# CLI tool (global)
dotnet tool install -g Atoll.Cli

# Project templates
dotnet new install Atoll.Templates

Or add package references directly to your .csproj:

<ItemGroup>
  <PackageReference Include="Atoll.Middleware" Version="0.1.*" />
  <PackageReference Include="Atoll.Lagoon" Version="0.1.*" />
</ItemGroup>

Use Atoll.Hosting.Aspire to add an Atoll dev server as a managed resource in a .NET Aspire AppHost project. The resource runs atoll dev with live reload and registers a /__health endpoint so the Aspire dashboard can track readiness.

dotnet add package Atoll.Hosting.Aspire

// AppHost Program.cs
var site = builder.AddAtollSite("my-site", "../MySite")
    .WithWriteDist(); // write rendered output to dist/ after each rebuild

var api = builder.AddProject<Projects.MyApi>("api")
    .WithReference(site);

The resource appears in the Aspire dashboard and shows as Running once the dev server passes its health check.

# Build in release mode
dotnet build -c Release

# Run tests
dotnet test

# Run the dev server (if using Atoll.Cli)
atoll dev

# Build static site
atoll build

See LICENSE for details.