FastComponents 0.0.0-alpha.0.32

FastComponents

Server-side Blazor components rendered as HTMX-powered HTML fragments -- build interactive web UIs with .NET 8 and zero client-side Blazor runtime.

Table of Contents

• The Problem
• The Solution
• Features
• Tech Stack
• Getting Started
• Usage
• Architecture
• Project Structure
• Roadmap
• Contributing
• License

The Problem

Building interactive web UIs with .NET typically means choosing between the full Blazor Server runtime (with WebSocket overhead and connection state) or Blazor WASM (with large download sizes). If you just want lightweight, server-rendered HTML fragments that respond to user interactions -- the HTMX model -- there is no first-class Blazor integration. You end up writing raw HTML strings or abandoning the Razor component model entirely.

The Solution

FastComponents bridges Blazor's server-side Razor component model with HTMX. You author components using familiar .razor syntax with full C# support, and FastComponents renders them as plain HTML fragments served via FastEndpoints. HTMX on the client handles partial page updates -- no WebSocket connections, no WASM downloads, just HTTP requests and HTML responses.

// Define a component with HTMX attributes using the HtmxTag helper
<HtmxTag
    As="button"
    HxGet="/api/counter?Count=1"
    HxSwap="outerHTML"
    HxTarget="#counter">
    Increment
</HtmxTag>

Features

• HtmxComponentBase -- base class with all htmx attributes as Blazor [Parameter] properties
• HtmxTag -- generic Razor component that renders any HTML element with htmx attributes
• HtmxComponentEndpoint<TComponent> -- serve components as HTML via FastEndpoints routes
• HtmxComponentEndpoint<TComponent, TParameters> -- typed parameter binding from query strings
• HtmxComponentParameters -- immutable record base with automatic query string serialization
• ComponentHtmlResponseService -- render any Blazor component to an HTML string on the server
• ClassNamesBuilder -- fluent, conditional CSS class builder (similar to classnames in JS)
• Hx.Swap constants and Hx.TargetId() helper for type-safe htmx attribute values
• Bundled htmx.min.js as a static web asset
• NuGet package with auto-generated API documentation
• HTML beautifier for formatted output (stub implemented)
• AOT compilation support (planned)
• Project template for dotnet new (planned)

Tech Stack

Getting Started

Prerequisites

• .NET SDK >= 8.0

Installation

Option 1 -- NuGet (recommended)

dotnet add package FastComponents

Option 2 -- From Source

git clone https://github.com/Atypical-Consulting/FastComponents.git
cd FastComponents
dotnet build

Setup

Register FastComponents in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Add FastComponents services (registers FastEndpoints + HTML renderer)
builder.Services.AddFastComponents();

var app = builder.Build();

app.UseStaticFiles();

// Map component endpoints
app.UseFastComponents();

app.Run();

Usage

Define a component

Create a Razor component that inherits from HtmxComponentBase:

@* Counter.razor *@
@inherits HtmxComponentBase<CounterEndpoint.CounterParameters>

<section id="block-counter">
    <HtmxTag
        As="button"
        HxGet="@Parameters.Increment()"
        HxSwap="@Hx.Swap.OuterHtml"
        HxTarget="@Hx.TargetId("block-counter")">
        Increment
    </HtmxTag>

    <span>Count: @Parameters.Count</span>
</section>

Wire it to an endpoint

// Counter.razor.cs
public class CounterEndpoint
    : HtmxComponentEndpoint<Counter, CounterEndpoint.CounterParameters>
{
    public override void Configure()
    {
        Get("/ui/blocks/counter");
        AllowAnonymous();
    }

    public record CounterParameters : HtmxComponentParameters
    {
        public int Count { get; init; } = 0;

        public string Increment()
        {
            var next = this with { Count = Count + 1 };
            return next.ToComponentUrl("/ui/blocks/counter");
        }
    }
}

When the button is clicked, htmx sends a GET request to /ui/blocks/counter?Count=1, FastComponents renders the Blazor component server-side, and the HTML fragment replaces the target element -- no JavaScript framework required.

Architecture

Browser (htmx)                    ASP.NET Server
+-----------------+                +-----------------------------------+
| HTML + htmx.js  | -- HTTP GET -> | FastEndpoints route               |
|                  |                |   -> HtmxComponentEndpoint        |
|                  |                |     -> ComponentHtmlResponseService|
|                  |                |       -> HtmlRenderer (Blazor SSR)|
| <-- HTML frag -- |                |     <- Rendered HTML fragment     |
+-----------------+                +-----------------------------------+

Project Structure

FastComponents/
├── src/
│   └── FastComponents/           # Core library (NuGet package)
│       ├── Components/
│       │   ├── Base/             # HtmxComponentBase, ClassNamesBuilder, interfaces
│       │   └── HtmxTag/         # Generic htmx-aware Razor component
│       ├── Endpoints/            # HtmxComponentEndpoint base classes
│       ├── Services/             # ComponentHtmlResponseService, HtmlBeautifier
│       ├── Utilities/            # Hx helper (swap constants, target helpers)
│       └── wwwroot/              # Bundled htmx.min.js
├── demo/
│   └── HtmxAppServer/           # Demo app (Counter, MovieCharacters examples)
├── docs/                         # Auto-generated API documentation
├── build/                        # Build scripts (versioning)
└── .github/workflows/            # CI pipeline (build, pack, validate, deploy)

Roadmap

• Implement HTML beautifier for formatted debug output
• Add AOT compilation support
• Publish a dotnet new project template
• Add unit and integration tests
• Expand component library with common UI patterns

Want to contribute? Pick any roadmap item and open a PR!

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit using conventional commits (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Apache-2.0 (c) 2020-2024 Atypical Consulting

Built with care by Atypical Consulting -- opinionated, production-grade open source.