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 libraryUsing Visual Studio:
- Right-click on your project in Solution Explorer and select “Manage NuGet Packages…”.
- Search for
Rizzyand click Install. - Search for
Rizzy.Htmxand 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@layoutdirective.AntiforgeryStrategy: Controls how antiforgery tokens are managed, important for security with HTMX POST requests.GenerateTokensPerPageis often suitable.
AddHtmx(config => ...): Configures the defaultHtmxConfigused 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
RzControllerorRzControllerWithViews. - 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
.razorfiles.
Refer to the specific documentation sections for details on Components, Forms, HTMX features, and Framework integration.