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

• Blazor Server & WebAssembly Support: Full support for both interactive server and client-side rendering modes
• 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

• .NET 10.0+ SDK
• Node.js (for npm packages and CSS building)

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" }
           ];
       });
   });
   
   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>
   

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:

• Website: https://talaryonlabs.com
• Email: hello@talaryonlabs.com

Changelog

Version History

• 1.0.0 (blzrtail) - Renamed from WebKit, .NET 10 support, enhanced theming
• 0.x.x (WebKit) - Initial releases under the WebKit name