Swap.Htmx

Installation

Multiple ways to add Swap.Htmx to your project.

The fastest way to get started. Our templates include everything pre-configured.

# Install templates
dotnet new install Swap.Templates

# Create a new project
dotnet new swap-modular -n MyApp   # Full modular architecture
# OR
dotnet new swap-mvc -n MyApp       # Simple MVC starter

# Navigate and run
cd MyApp/src   # (or just cd MyApp for swap-mvc)
libman restore
dotnet run

Option 2: Add to Existing Project

1. Install the NuGet Package

dotnet add package Swap.Htmx

For real-time features (SSE/WebSockets):

dotnet add package Swap.Htmx.Realtime

2. Configure Services (Program.cs)

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddSwapHtmx();  // Add Swap.Htmx services

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.UseSwapHtmx();  // Add Swap.Htmx middleware

app.MapControllers();
app.Run();

3. Add Client Scripts (_Layout.cshtml)

Add these before </head>:

CDN (Quick Start):

<link rel="stylesheet" href="~/_content/Swap.Htmx/css/swap.css" />
<script src="https://unpkg.com/[email protected]"></script>
<script src="~/_content/Swap.Htmx/js/swap.client.js"></script>

LibMan (Local Assets):

First, create libman.json:

{
  "version": "1.0",
  "defaultProvider": "unpkg",
  "libraries": [
    {
      "library": "[email protected]",
      "destination": "wwwroot/lib/htmx/dist/"
    }
  ]
}

Then restore and reference:

libman restore

<link rel="stylesheet" href="~/_content/Swap.Htmx/css/swap.css" />
<script src="~/lib/htmx/dist/htmx.min.js"></script>
<script src="~/_content/Swap.Htmx/js/swap.client.js"></script>

4. Register Tag Helpers (_ViewImports.cshtml)

@addTagHelper *, Swap.Htmx

Verifying Installation

Create a simple controller to test:

using Swap.Htmx;

public class TestController : SwapController
{
    [HttpGet("/test")]
    public IActionResult Index() => SwapView();
}

Create Views/Test/Index.cshtml:

<h1>It works!</h1>
<p>Swap.Htmx is installed and ready.</p>

Navigate to /test. If you see the page, you're ready to build!

Next Steps