blzrtail ist eine ASP.NET Blazor-Bibliothek mit fertigen Komponenten und Utilities für moderne Webanwendungen. Basierend auf Tailwind CSS, DaisyUI und Alpine.js bietet es responsive UI-Elemente, State-Management-Helper und Integrationsmuster – alles für schnelle, wartbare Frontends. Blazor, aber einfacher.
  • C# 59.5%
  • HTML 31.4%
  • JavaScript 9.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
ferociousbyte 44a6c256fb Talaryon.Toolbox 1.7.6
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 13:53:53 +01:00
docs Migration doc: no flicker between pages, warnings, where it goes live 2026-10-27 19:52:32 +01:00
src/blzrtail Talaryon.Toolbox 1.7.6 2026-11-05 13:53:53 +01:00
.gitignore Add initial implementation of WebKit components and services for Talaryon. 2026-08-14 22:38:44 +02:00
blzrtail.slnx Add initial implementation of WebKit components and services for Talaryon. 2026-08-14 22:38:44 +02:00
README.md Status codes on static pages: 404 in place, 503 for api-offline, one <title> 2026-10-27 12:17:24 +01:00

blzrtail

blzrtail (formerly known as WebKit) is a modern web application framework from Talaryon Labs for building professional, responsive web applications using Blazor and .NET 10+. It combines the power of Blazor with a comprehensive UI toolkit, including Tailwind CSS and DaisyUI, to help you build beautiful applications quickly.

Overview

blzrtail provides developers with a complete foundation for building Blazor-based web applications. It eliminates the need to set up common infrastructure from scratch, allowing you to focus on your application's unique features and business logic.

Built on the rock-solid foundation of .NET and Blazor, blzrtail integrates seamlessly with the modern web development ecosystem while providing a structured, opinionated approach to building web applications.

Features

Core Framework

  • Static server rendering by default: pages are plain HTML, no circuit and no WebAssembly; Interactive Server, WebAssembly and Auto only where an app asks for them (WebKitSettings.Interactivity)
  • Component-Based Architecture: Built on Razor components for reusable, maintainable code
  • .NET 10+ Ready: Fully compatible with the latest .NET platform

UI & Styling

  • Tailwind CSS Integration: Utility-first CSS framework for rapid styling
  • DaisyUI Support: Pre-configured with DaisyUI for beautiful, accessible components
  • Theme System: Customizable light and dark themes with comprehensive color variables
  • Responsive Design: Mobile-first approach with responsive breakpoints

Pre-built Components

  • Layout System: Navbar, Footer, MainLayout with proper structure
  • Page Components: Ready-to-use page templates
  • UI Components: Buttons, Cards, Hero sections, Feature grids, and more
  • Form Components: Styled form elements with validation support

Infrastructure

  • Metadata Configuration: Easy configuration of application name, title, description, and social meta tags
  • Navigation System: Configurable navigation links through options pattern
  • Internationalization: Built-in support for multiple cultures and languages
  • Authentication: Extensions for OIDC and Token-based authentication
  • Rate Limiting: Built-in rate limiting support for API endpoints

Getting Started

Prerequisites

Installation

As a Submodule

# Clone your project
git clone <your-repo-url>
cd <your-project>

# Add blzrtail as a submodule
git submodule add <blzrtail-repo-url> libs/blzrtail
git submodule update --init --recursive

Basic Setup

  1. Add the blzrtail namespace to your _Imports.razor:

    @using Talaryon.WebKit
    
  2. Configure blzrtail in your Program.cs:

    using Talaryon.WebKit;
    using Talaryon.WebKit.Services.Options;
    
    var builder = WebApplication.CreateBuilder(args);
    
    // Add WebKit services
    builder.Services.AddWebKitComponents();
    
    var app = builder.BuildWithWebKit<YourApp.Components.App>(webkit =>
    {
        // Configure metadata
        webkit.Configure<WebKitMetaOptions>(options =>
        {
            options.ApplicationName = "Your App";
            options.Title = "Your App Title";
            options.Description = "Your app description";
            options.BaseUrl = "https://yourapp.com";
        });
    
        // Configure navigation
        webkit.Configure<WebKitNavBarOptions>(options =>
        {
            options.Links = [
                new() { Text = "Home", Url = "/" },
                new() { Text = "About", Url = "/about" }
            ];
        });
    
        // The page /webkit/api-offline, for visitors while the API is not reachable: a logo of the site itself
        // (not served by the API), the text, and how to tell that the API is back
        webkit.Configure<WebKitApiOfflineOptions>(options =>
        {
            options.LogoUrl = "/logo.svg";
            options.Message = ["Our API is currently offline.", "Please try again later."];
            options.IsAvailable = services => services.GetRequiredService<MyApi>().IsAvailableAsync();
        });
    });
    
    app.Run();
    
  3. Create your root component (inheriting from WebKitComponent):

    @inherits Talaryon.WebKit.WebKitComponent
    
    <WebKitLayout>
        <Header>
            <NavbarComponent />
        </Header>
        <Content>
            @Body
        </Content>
        <Footer>
            <FooterComponent />
        </Footer>
    </WebKitLayout>
    

Render Modes

blzrtail renders statically by default: every page is server-rendered HTML, without a SignalR circuit and without WebAssembly. /_blazor is not mapped and the Content-Security-Policy allows no WebSockets. That is the right mode for websites; forms post the classic way.

Moving an existing site over: docs/migrate-to-static-ssr.md.

An app that needs interactivity asks for it, and then places render modes where it needs them:

builder.Services.AddWebKitComponents(settings =>
{
    settings.Interactivity = WebKitInteractivity.Server;   // or WebAssembly, or Auto (both)
});
  • Without it, any @rendermode fails at runtime: there is no endpoint for the mode
  • No component of blzrtail has a render mode of its own. In an app whose pages are interactive (<Routes @rendermode="InteractiveServer"/>), give WebKitMeta the same mode where it is placed, so the pages reach it: <WebKitMeta @rendermode="InteractiveServer"/>
  • WebKitReconnect and blzrtail.lib.module.js (the reconnect banner, saved drafts, the Web Lock) only act on a circuit
  • blazor.web.js is optional on a static site: without it every link and form is a full page load; with it Blazor's enhanced navigation and forms work

Forms on a static page

WebKitForm posts the page itself. Give it a FormName and bind the model with [SupplyParameterFromForm]:

@page "/contact"

<WebKitForm ContextModel="@Model!" FormName="contact" OnSubmit="SendAsync">
    <Form>
        <InputText @bind-Value="Model!.Email" class="input" />
    </Form>
</WebKitForm>

@code {
    // no initializer: a post could overwrite it with null (analyzer BL0008)
    [SupplyParameterFromForm(FormName = "contact")]
    private ContactModel? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private async Task SendAsync(WebKitFormCallbackArgs args)
    {
        // send ...
        args.Component.Success();
    }
}

The Input* components name their fields after the expression (Model.Email), which is what the binding reads. Validation runs on the server when the form is posted; @onclick, @bind while typing and IJSRuntime don't work on a static page. Small interactions in the browser (menus, toggles) belong to plain JavaScript or Alpine.js. A page deriving from WebKitPage initializes the model in OnPageInitialized instead, since WebKitPage uses OnInitialized.

Status codes

IWebKitNavigation.HandleError(404) answers a static render in place: the response is a 404 with the status code page, at the requested address (NavigationManager.NotFound). In a circuit, and for other codes, it sends the visitor to /webkit/status-code/{code}, which answers with that code. SetStatusCode sets the code of a static response, e.g. for a page of your own; /webkit/api-offline answers 503.

Project Structure

blzrtail/
├── Components/           # Core Razor components
│   └── WebKitComponent.cs       # Base component class
├── Models/               # Data models and DTOs
├── Providers/            # Service providers
├── Services/            # Service implementations
│   ├── Options/          # Configuration options
│   └── ...
├── blzrtail.csproj        # Project file
└── WebKitExtensions.cs   # Extension methods

Configuration Options

WebKitMetaOptions

Configure application metadata, SEO, and social sharing:

webkit.Configure<WebKitMetaOptions>(options =>
{
    options.ApplicationName = "My App";
    options.Title = "My App | Home";
    options.Description = "Description for SEO";
    options.Image = "assets/images/og-image.jpg";
    options.BaseUrl = "https://myapp.com";
    options.Favicon = "favicon.ico";
});

WebKitNavBarOptions

Configure navigation links:

webkit.Configure<WebKitNavBarOptions>(options =>
{
    options.Links = [
        new() { Text = "Home", Url = "/" },
        new() { Text = "Features", Url = "/features" },
        new() { Text = "Contact", Url = "/contact" }
    ];
});

WebKitI18NOptions

Configure internationalization:

webkit.Configure<WebKitI18NOptions>(options =>
{
    options.RequestCultureProviders = ["en-US", "de-AT", "fr-FR"];
    options.CultureInfo = CultureInfo.CreateSpecificCulture("en-US");
});

Styling & Theming

CSS Architecture

blzrtail uses Tailwind CSS with DaisyUI for styling. The main stylesheet should import the necessary files:

@import "./fonts.css";
@import "./variables.css";

@import "tailwindcss";
@import "tailwindcss-animated";

@config "../tailwind.config.js";

@plugin "tailwind-tint-color";
@plugin "daisyui";

Theme Configuration

Define custom themes in your CSS:

@plugin "daisyui/theme" {
    name: "blzrtail-light";
    default: true;
    prefersdark: false;
    color-scheme: "light";
    
    --color-primary: #00a9a7;
    --color-secondary: #061827;
    --color-accent: #0b2435;
    /* ... more color variables */
}

@plugin "daisyui/theme" {
    name: "blzrtail-dark";
    default: false;
    prefersdark: true;
    color-scheme: "dark";
    
    --color-primary: #14c6c2;
    --color-secondary: #ffffff;
    /* ... more color variables */
}

Building CSS

To build the CSS file during development:

npx @tailwindcss/cli -i Styles/app.css -o wwwroot/css/app.generated.css --watch

Authentication

OIDC Authentication

blzrtail provides extensions for OpenID Connect authentication:

builder.Services.AddWebKitOidcAuthentication(options =>
{
    options.Authority = "https://your-identity-provider.com";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.ResponseType = "code";
});

Token Authentication

For API token-based authentication:

builder.Services.AddWebKitTokenAuthentication(options =>
{
    options.Issuer = "your-issuer";
    options.Audience = "your-audience";
    options.Secret = "your-secret-key";
});

Rate Limiting

blzrtail includes built-in rate limiting support:

builder.Services.AddWebKitRateLimiting(options =>
{
    options.DefaultLimit = 100;
    options.DefaultWindow = TimeSpan.FromMinutes(1);
    options.EndpointLimits = new Dictionary<string, RateLimitOptions>
    {
        ["/api/endpoint"] = new RateLimitOptions
        {
            Limit = 10,
            Window = TimeSpan.FromSeconds(30)
        }
    };
});

Component Development

Creating a WebKit Component

@inherits Talaryon.WebKit.WebKitComponent

@code {
    // Your component logic here
}

<!-- Your component markup here -->

Page Components

Pages should inherit from WebKitPage:

@page "/my-page"
@layout MainLayout
@inherits Talaryon.WebKit.WebKitPage

@code {
    protected override void OnPageInitialized()
    {
        Title = "My Page Title";
        Description = "My page description";
    }
}

Best Practices

Project Organization

  • Keep components small and focused
  • Use the Components/ directory for reusable UI elements
  • Use the Pages/ directory for routeable pages
  • Group related components in subdirectories

Styling

  • Use Tailwind utility classes for styling
  • Create custom components for repeated patterns
  • Use DaisyUI components when available
  • Define theme colors in CSS variables

Configuration

  • Use the options pattern for all configuration
  • Store secrets in user secrets or environment variables
  • Validate configuration on startup

Migration from WebKit

If you're migrating from the previous WebKit framework:

  1. Namespace Changes: Update all references from Talaryon.WebKit to Talaryon.blzrtail (or keep using the old namespace as it's still supported)

  2. Configuration: The configuration system remains largely the same, but some option names may have been updated

  3. CSS: Theme names have changed from template-* to blzrtail-*

  4. NuGet Package: The package name has changed from Talaryon.WebKit to Talaryon.blzrtail

Contributing

We welcome contributions to blzrtail! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Write tests for new functionality
  5. Submit a pull request

License

blzrtail is proprietary software from Talaryon Labs. For licensing information, please contact Talaryon Labs.

Support

For questions, issues, or support requests:

Changelog

Version History

  • 1.1.0 - Static server rendering is the default; interactive render modes only with WebKitSettings.Interactivity. WebKitMeta, WebKitFooter and WebKitCurrencyView no longer carry a render mode, WebKitForm takes FormName and Enhance and awaits OnSubmit
  • 1.0.0 (blzrtail) - Renamed from WebKit, .NET 10 support, enhanced theming
  • 0.x.x (WebKit) - Initial releases under the WebKit name