Blazouter 1.0.2

Blazouter 🚀

A powerful React Router-like routing library for Blazor applications. Blazouter brings the best features of React Router to the Blazor ecosystem.

🌟 Why Blazouter?

Blazor's built-in routing is functional but lacks many modern features that developers expect from frameworks like React Router. Blazouter fills this gap by providing:

• ✅ True nested routing - Not just @page directives
• ✅ Built-in route guards - Protect your routes easily
• ✅ Lazy loading - Load components on-demand
• ✅ Beautiful transitions - Smooth animations between routes
• ✅ Type-safe - Full IntelliSense support
• ✅ Programmatic navigation - Navigate imperatively with ease

✨ Features

Blazouter addresses the limitations of traditional Blazor routing:

Key Features

• 🎯 Nested Routes: Define complex hierarchical route structures easily
• 🔒 Route Guards: Protect routes with authentication and authorization logic
• ⚡ Lazy Loading: Load components on-demand for better performance
• 🎨 Route Transitions: Beautiful animations when navigating between routes
• 🔗 Programmatic Navigation: Navigate imperatively with enhanced navigation service
• 📊 Route Parameters: Easy access to route and query parameters
• 🎭 Dynamic Components: Load components dynamically based on routes

🚀 Quick Start

Installation

dotnet add package Blazouter

Setup

1. Add Blazouter services in Program.cs:

using Blazouter.Extensions;

builder.Services.AddBlazouter();

2. Define routes in App.razor:

@using Blazouter.Components
@using Blazouter.Models

<Blazouter.Components.Router Routes="@_routes">
    <NotFound>
        <h1>404 - Page Not Found</h1>
    </NotFound>
</Blazouter.Components.Router>

@code {
    private List<RouteConfig> _routes = new()
    {
        new RouteConfig
        {
            Path = "/",
            Component = typeof(Pages.Home),
            Transition = "fade"
        },
        new RouteConfig
        {
            Path = "/users",
            Component = typeof(Pages.UserLayout),
            Children = new List<RouteConfig>
            {
                new RouteConfig 
                { 
                    Path = ":id", 
                    Component = typeof(Pages.UserDetail) 
                }
            }
        }
    };
}

3. Include the CSS in your index.html:

<link rel="stylesheet" href="_content/Blazouter/blazouter.css" />

📖 Usage Examples

Basic Routing

new RouteConfig
{
    Path = "/about",
    Component = typeof(About),
    Title = "About Us",
    Transition = "slide"
}

Nested Routes

new RouteConfig
{
    Path = "/products",
    Component = typeof(ProductLayout),
    Children = new List<RouteConfig>
    {
        new RouteConfig 
        { 
            Path = "", 
            Component = typeof(ProductList),
            Exact = true 
        },
        new RouteConfig 
        { 
            Path = ":id", 
            Component = typeof(ProductDetail) 
        }
    }
}

Use <RouterOutlet /> in the parent component to render child routes:

@using Blazouter.Components

<div class="layout">
    <h1>Products</h1>
    <RouterOutlet />
</div>

Route Guards (Protected Routes)

new RouteConfig
{
    Path = "/admin",
    Component = typeof(AdminPanel),
    Guards = new List<Type> { typeof(AuthGuard) }
}

Create a guard:

using Blazouter.Guards;
using Blazouter.Models;

public class AuthGuard : IRouteGuard
{
    public async Task<bool> CanActivateAsync(RouteMatch match)
    {
        // Check authentication
        return await IsAuthenticated();
    }

    public Task<string?> GetRedirectPathAsync(RouteMatch match)
    {
        return Task.FromResult<string?>("/login");
    }
}

Lazy Loading

new RouteConfig
{
    Path = "/reports",
    ComponentLoader = async () =>
    {
        // Simulate loading delay or dynamic import
        await Task.Delay(100);
        return typeof(ReportsPage);
    }
}

Route Links

@using Blazouter.Components

<nav>
    <RouterLink Href="/" Exact="true" ActiveClass="active">Home</RouterLink>
    <RouterLink Href="/about" ActiveClass="active">About</RouterLink>
    <RouterLink Href="/users" ActiveClass="active">Users</RouterLink>
</nav>

Programmatic Navigation

@inject RouterNavigationService NavService

<button @onclick="NavigateToUser">Go to User</button>

@code {
    private void NavigateToUser()
    {
        NavService.NavigateTo("/users/123");
    }
}

Access Route Parameters

@using Blazouter.Services
@inject RouterStateService RouterState

<h1>User: @_userId</h1>

@code {
    private string? _userId;

    protected override void OnInitialized()
    {
        _userId = RouterState.GetParam("id");
    }
}

🎨 Route Transitions

Blazouter includes built-in transitions:

• fade - Fade in animation
• slide - Slide from left animation
• slide-up - Slide from bottom animation
• scale - Scale in animation

new RouteConfig
{
    Path = "/",
    Component = typeof(Home),
    Transition = "fade"
}

🏗️ Project Structure

Blazouter/
├── src/
│   └── Blazouter/                 # Main library
│       ├── Components/            # Router components
│       │   ├── Router.razor
│       │   ├── RouterLink.razor
│       │   └── RouterOutlet.razor
│       ├── Guards/                # Route guard interfaces
│       ├── Models/                # Route models
│       ├── Services/              # Routing services
│       └── wwwroot/              # CSS and assets
└── samples/
    └── Blazouter.Sample/          # Sample application

🎮 Running the Sample

To see Blazouter in action:

cd samples/Blazouter.Sample
dotnet run

Then navigate to https://localhost:5001 in your browser.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

📊 Project Stats

• Supported .NET versions: .NET 6.0, 7.0, 8.0, 9.0, 10.0
• Platform: Blazor WebAssembly & Blazor Server
• License: MIT
• Package: NuGet

🔗 Links

• Documentation
• Changelog
• Contributing Guide
• Issue Tracker
• Sample Application

🙏 Acknowledgments

Inspired by React Router and built to bring similar capabilities to the Blazor ecosystem.

📝 Roadmap

• Query string helpers and utilities
• Route middleware support
• Better TypeScript integration for JS interop
• Advanced caching strategies
• Performance optimizations

⭐ Show Your Support

If you find Blazouter helpful, please consider giving it a star on GitHub! It helps the project grow and reach more developers.

Made with ❤️ for the Blazor community