Getting Started
This guide provides instructions on how to incorporate the Rizzy library into your ASP.NET projects. Rizzy leverages .NET 8 capabilities to enhance your web application development process, particularly focusing on integrating Razor Components with HTMX.
Requirements
- .NET Version: .NET 8 or newer.
Installation
Rizzy is available as a NuGet package. You can install it using the .NET CLI or the Visual Studio NuGet Package Manager.
Using .NET CLI:
dotnet add package Rizzy
dotnet add package Rizzy.Htmx # Recommended: Also add the HTMX helper library
Using Visual Studio:
- Right-click on your project in Solution Explorer and select “Manage NuGet Packages…”.
- Search for
Rizzy
and click Install. - Search for
Rizzy.Htmx
and click Install.
For the latest versions and more details, visit the package pages:
Configuration (Program.cs)
After installing the packages, you need to configure Rizzy and its HTMX integration in your Program.cs
file. This involves registering necessary services and setting up configurations.
using Rizzy;
using Rizzy.Configuration;
using Rizzy.Htmx;
using Rizzy.Htmx.Antiforgery; // For AntiforgeryStrategy enum
using YourApp.Components.Layout; // Replace with your actual layout namespaces
var builder = WebApplication.CreateBuilder(args);
// Add standard services like Controllers, Razor Components etc.
builder.Services.AddControllers(); // If using MVC
builder.Services.AddRazorComponents();
// --- Rizzy Configuration ---
// 1. Add Rizzy Core Services
// This configures Rizzy-specific services and options.
builder.Services.AddRizzy(config =>
{
// RootComponent: The main component wrapping your app.
// HtmxApp<T> ensures layouts aren't re-rendered on HTMX partial requests.
config.RootComponent = typeof(HtmxApp<AppLayout>); // Replace AppLayout with your root layout
// DefaultLayout: Applied to components without an explicit @layout directive.
// HtmxLayout<T> handles switching between full/minimal layouts for HTMX requests.
config.DefaultLayout = typeof(HtmxLayout<MainLayout>); // Replace MainLayout with your default content layout
});
// 2. Add HTMX Configuration Services (Optional but Recommended)
// This configures the *default* HTMX behavior via HtmxConfig.
builder.Services.AddHtmx(config =>
{
// Example: Restrict HTMX requests to the same origin by default.
config.SelfRequestsOnly = true;
// Example: Enable generation of nonces for inline styles/scripts via IRizzyNonceProvider
// Requires IRizzyNonceProvider to be registered (AddRizzy does this).
// Use with caution regarding CSP implications. See CSP docs.
// config.GenerateScriptNonce = true;
// config.GenerateStyleNonce = true;
// Add other default HTMX settings as needed...
});
// --- End Rizzy Configuration ---
// --- Build the App ---
var app = builder.Build();
// --- Configure Middleware Pipeline ---
// Ensure middleware is in the correct order
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
// Add Authentication/Authorization middleware if used
app.UseAntiforgery(); // Crucial: Must be after UseRouting and UseAuthentication/UseAuthorization
// Add Rizzy Middleware (Handles specific HTMX request processing, like Nonce headers)
app.UseRizzy();
// --- Map Endpoints ---
app.MapControllers(); // If using MVC
// Map Minimal API endpoints...
app.Run();
Configuration Details Explained
AddRizzy(config => ...)
: Configures the core Rizzy library.RootComponent
: TypicallyHtmxApp<YourAppLayout>
to handle layout switching correctly for HTMX requests.DefaultLayout
: TypicallyHtmxLayout<YourMainLayout>
applied to components without an@layout
directive.AntiforgeryStrategy
: Controls how antiforgery tokens are managed, important for security with HTMX POST requests.GenerateTokensPerPage
is often suitable.
AddHtmx(config => ...)
: Configures the defaultHtmxConfig
used when rendering the<HtmxConfigHeadOutlet />
without a specific configuration name. See HTMX Configuration for all options.app.UseAntiforgery()
: Essential for security. Must be placed correctly in the middleware pipeline.app.UseRizzy()
: Adds the Rizzy middleware for handling specific HTMX interactions (e.g., response nonce headers). Place it afterUseAntiforgery()
.
Conclusion
With Rizzy installed and configured, you can now start building your application using Razor Components rendered server-side and enhanced with HTMX. Remember to:
- Inherit your MVC controllers from
RzController
orRzControllerWithViews
. - Use
View<TComponent>
andPartialView<TComponent>
methods in your controllers/endpoints. - Utilize Rizzy’s components (like
RzInput*
,HtmxSwapService
) as needed. - Add HTMX attributes directly to your HTML elements within
.razor
files.
Refer to the specific documentation sections for details on Components, Forms, HTMX features, and Framework integration.