Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/deans-bradley/blazor-wasm-template

A comprehensive full-stack template for Blazor WebAssembly applications built with .NET 9, featuring a clean waterfall architecture and modern UI components.
https://github.com/deans-bradley/blazor-wasm-template

blazor blazor-webassembly csharp dotnet fastendpoints mudblazor template

Last synced: about 1 month ago
JSON representation

A comprehensive full-stack template for Blazor WebAssembly applications built with .NET 9, featuring a clean waterfall architecture and modern UI components.

Awesome Lists containing this project

README 

          
# Blazor WASM Template



A comprehensive full-stack template for Blazor WebAssembly applications built with .NET 10 (preview), featuring a clean waterfall architecture and modern UI components.



## Features



- **Modern Stack**: Built on .NET 10 (preview) with the latest Blazor WebAssembly

- **Clean Architecture**: Implements waterfall architecture with clear separation of concerns

- **MVVM Pattern**: Client-side MVVM design pattern with dependency injection

- **Rich UI**: Pre-configured with [MudBlazor](https://mudblazor.com/) for beautiful, responsive components

- **Fast APIs**: Powered by [FastEndpoints](https://fast-endpoints.com/) for high-performance API development

- **Local Storage**: Integrated [Blazored LocalStorage](https://github.com/Blazored/LocalStorage) for client-side data persistence

- **Ready to Use**: Comes pre-configured and ready for development



## Project Structure



```

blazor-wasm-template/

├── .github/                # GitHub Actions workflows

│   └── workflows/

│       └── deploy.yaml     # Automated deployment workflow

├── .vscode/                # VS Code configuration

│   ├── launch.json         # Debug configurations

│   ├── settings.json       # Workspace settings

│   └── tasks.json          # Build and run tasks

├── src/                    # Source code directory

│   ├── API/                # Web API layer with FastEndpoints

│   ├── BlazorApp.Client/   # Blazor WebAssembly client application

│   ├── BlazorApp.Shared/   # Shared contracts and DTOs

│   ├── BlazorApp.Utils/    # Shared business logic utilities

│   ├── BLL/                # Business Logic Layer

│   ├── DAL/                # Data Access Layer

│   └── Models/             # Domain models and entities

└── BlazorApp.sln           # Solution file (located in src/)

```



## Architecture Overview



This template implements a waterfall architecture pattern with clear separation of concerns:



- **API Layer**: Handles HTTP requests and routing using FastEndpoints

- **BLL (Business Logic Layer)**: Contains business rules and application logic

- **DAL (Data Access Layer)**: Manages data persistence and retrieval

- **Client Layer**: Blazor WebAssembly frontend with MudBlazor components using MVVM pattern

- **Shared Layer**: Common contracts, DTOs, and utilities used across layers

- **Utils Layer**: Cross-cutting concerns and shared utilities

- **CI/CD**: Automated deployment via GitHub Actions and Azure Pipelines

- **Development**: Enhanced VS Code integration with pre-configured tasks and debugging



## Data Flow Architecture



The application follows a structured data flow pattern that ensures clean separation of concerns and maintainable code:



### Client-Side Flow (MVVM with DI)



The client uses the **Model-View-ViewModel (MVVM)** pattern with dependency injection for clean architecture:



**1. View (Blazor Component) → ViewModel**

```razor

@page "/weather"

@inject IWeatherViewModel viewModel



Get Today's Weather



@code {

    private async Task LoadWeather()

    {

        TodaysWeatherResponse weatherResponse = await viewModel.GetTodaysWeather();

        // Handle response...

    }

}

```



**2. ViewModel → HTTP Service**

```csharp

public class WeatherViewModel(IHttpService httpService) : IWeatherViewModel

{

    private readonly IHttpService _httpService = httpService;



    public async Task GetTodaysWeather()

    {

        TodaysWeatherResponse response = await _httpService.Get("/weather/today");

        return response;

    }

}

```



### Server-Side Flow (API → BLL → DAL)



**3. API Endpoint → Business Logic Layer**

```csharp

public class GetTodaysWeather(IWeatherService weatherService) : EndpointWithoutRequest

{

    private readonly IWeatherService _weatherService = weatherService;



    public override void Configure()

    {

        Get("/weather/today");

        AllowAnonymous();

    }



    public override async Task HandleAsync(CancellationToken ct)

    {

        TodaysWeatherResponse response = await _weatherService.GetTodaysWeather();

        await SendAsync(response, cancellation: ct);

    }

}

```



**4. Business Logic Layer → Data Access Layer**

```csharp

public class WeatherService(IWeatherRepository weatherRepository) : IWeatherService

{

    private readonly IWeatherRepository _weatherRepository = weatherRepository;



    public async Task GetTodaysWeather()

    {

        WeatherData weatherData = await _weatherRepository.GetCurrentWeatherAsync();

        

        // Apply business logic, transformations, validations

        return new TodaysWeatherResponse

        {

            Temperature = weatherData.Temperature,

            Description = weatherData.Description,

            // ... other mappings

        };

    }

}

```



**5. Data Access Layer → Database/External APIs**

```csharp

public class WeatherRepository : IWeatherRepository

{

    public async Task GetCurrentWeatherAsync()

    {

        // Fetch from database, external API, or other data source

        // Return raw data model

    }

}

```



### Complete Request Flow



```mermaid

graph TD

    A[Blazor Component] --> B[ViewModel]

    B --> C[HTTP Service]

    C --> D[API Endpoint]

    D --> E[Business Service]

    E --> F[Repository/DAL]

    F --> G[Database/External API]

    

    G --> F

    F --> E

    E --> D

    D --> C

    C --> B

    B --> A

```



**Flow Summary:**

1. **View** triggers an action and calls the **ViewModel**

2. **ViewModel** uses **IHttpService** to make HTTP requests to the API

3. **API Endpoint** receives the request and delegates to the **Business Logic Layer**

4. **BLL Service** applies business rules and calls the **Data Access Layer**

5. **DAL Repository** retrieves/persists data from the database or external services

6. Response flows back up the chain: DAL → BLL → API → Client → ViewModel → View



This architecture ensures:

- **Single Responsibility**: Each layer has a clear purpose

- **Dependency Inversion**: Higher layers depend on abstractions, not implementations

- **Testability**: Each layer can be unit tested independently

- **Maintainability**: Changes in one layer don't cascade to others

- **Scalability**: Easy to extend and modify individual components



## Getting Started



### Prerequisites



- [.NET 10 SDK (preview)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed on your machine

- **Visual Studio Code** with C# Dev Kit extension, or **Visual Studio 2026 (Insiders)**

  

> **Note**: This project requires .NET 10 preview and is only supported in VS Code or Visual Studio 2026 (Insiders). Earlier versions of Visual Studio are not supported.



### Installation



1. **Clone the repository**

   ```bash

   git clone https://github.com/deans-bradley/blazor-wasm-template.git

   cd blazor-wasm-template

   ```



2. **Restore dependencies**

   ```bash

   dotnet restore src/

   ```



3. **Build the solution**

   ```bash

   dotnet build src/

   ```



### Running the Application



The API and client run simultaneously - no need to start them separately.



#### Using Visual Studio 2026 (Insiders)

- Press `F5` to start debugging, or

- Use `Ctrl` + `F5` to run without debugging



#### Using VS Code

The project includes pre-configured VS Code tasks for easy development:



**Tasks**

- **Build API**: Builds the API project

- **App (Dev)**: Builds and runs the app in `Development`, launches the app in the browser 



- In the **Run and Debug** panel, select **App (Dev)** in the dropdown.

- Press `F5`** to start debugging (uses the configured launch profile).



#### Using Command Line

```bash

# From the root directory

dotnet run --project src/API

```



Once running, navigate to `https://localhost:{port}` in your browser (the exact port will be displayed in the console).



## Deployment



This template includes automated deployment via GitHub Actions:



### GitHub Actions Workflow



The project includes a `deploy.yaml` workflow in `.github/workflows/` that provides:



- **Automated CI/CD**: Builds and deploys your application on code changes

- **Multi-environment support**: Configure different deployment targets

- **Dependency caching**: Faster build times with NuGet package caching

- **Security**: Uses GitHub secrets for secure deployment credentials



To set up deployment:



1. Configure your deployment target (Azure, AWS, etc.) in the `deploy.yaml` file

2. Add required secrets to your GitHub repository settings

3. Push changes to trigger automatic deployment



> **Note**: Review and customize the deployment workflow according to your hosting requirements.



## Recommended VS Code Extensions



For the best development experience, install these extensions:

- **C# Dev Kit** - Essential C# support and debugging

- **C#** - Language support for C#



## Customization



### Updating Template Name



To customize the template for your project:



1. Use your IDE's "Find and Replace in Files" feature

2. Search for `BlazorApp` throughout the entire solution

3. Replace with your desired project name

4. Update namespaces and assembly names accordingly



**Tip**: Make sure to update folder names, project files (.csproj), and namespace declarations.



## Contributing



I am open to contributions. Please follow these steps:



1. **Fork the repository**

2. **Create a feature branch**

   ```bash

   git checkout -b feature/your-feature-name

   ```

3. **Make your changes and commit**

   ```bash

   git commit -m 'Add: your feature description'

   ```

4. **Push to your branch**

   ```bash

   git push origin feature/your-feature-name

   ```

5. **Open a Pull Request**



Please ensure your code follows the existing patterns and includes appropriate tests where applicable.



## Technologies Used



- [**Blazor WebAssembly**](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor) - Client-side web UI framework

- [**FastEndpoints**](https://fast-endpoints.com/) - High-performance API framework

- [**MudBlazor**](https://mudblazor.com/) - Material Design component library

- [**Blazored LocalStorage**](https://github.com/Blazored/LocalStorage) - Browser local storage wrapper

- **.NET 10 (preview)** - Latest .NET framework preview



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



## Acknowledgments



Special thanks to the creators and maintainers of these excellent frameworks and libraries that make this template possible.



## Changelog



### Version 1.1.0

- Update project to .NET 10 (preview)

- Update all project dependencies to latest versions

- Add automated deployment with GitHub Actions (`deploy.yaml`)

- Add comprehensive VS Code configuration (`.vscode/` directory)

  - `launch.json`: Debug configurations for API and client

  - `tasks.json`: Build and run tasks for streamlined development

  - `settings.json`: Optimized workspace settings for .NET development

- Reorganize project structure: move source code to `src/` directory

- Enhanced development workflow with pre-configured debugging and build tasks



### Version 1.0.1

- Update README with corrections and add acknowledgment message



### Version 1.0.0

- Initial release with core functionality

- API project with fastendpoints

- Blazor WASM client project with MudBlazor

- DAL, BLL, Models, Utils, and Shared libraries