https://github.com/phmatray/minimalhtmx
A minimal .NET template for creating HTMX-based Blazor projects
https://github.com/phmatray/minimalhtmx
blazor dotnet htmx template
Last synced: 5 months ago
JSON representation
A minimal .NET template for creating HTMX-based Blazor projects
- Host: GitHub
- URL: https://github.com/phmatray/minimalhtmx
- Owner: phmatray
- License: mit
- Created: 2024-11-04T16:11:41.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-17T16:05:24.000Z (9 months ago)
- Last Synced: 2025-08-01T00:53:15.612Z (5 months ago)
- Topics: blazor, dotnet, htmx, template
- Language: JavaScript
- Homepage:
- Size: 204 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MinimalHtmx Template đĻđ
A minimal .NET template for creating HTMX-based Blazor projects, leveraging Carter for routing and component-based architectures. This template provides a foundation for building interactive, server-driven web applications with Blazor and HTMX.
## Table of Contents đ
* [MinimalHtmx Template đĻđ](#minimalhtmx-template-)
* [Table of Contents đ](#table-of-contents-)
* [Overview đ](#overview-)
* [Features â¨](#features-)
* [Installation âī¸](#installation-)
* [Usage đ](#usage-)
* [Running the Project âļī¸](#running-the-project-)
* [Project Structure đī¸](#project-structure-)
* [Customization âī¸](#customization-)
* [Adding New Routes â](#adding-new-routes-)
* [Modifying Components đ ī¸](#modifying-components-)
* [Using AppState đž](#using-appstate-)
* [Contributing đ¤](#contributing-)
* [License đ](#license-)
* [About âšī¸](#about-âš)
* [Quick Start Guide đ](#quick-start-guide-)
## Overview đ
This template includes:
- 2 Blazor components (`PageCounter` and `PageContact`) with HTMX integration for building dynamic, server-side pages.
- Carter-based routing to handle minimal APIs seamlessly.
- Pre-configured HTMX components (`HxCounter`, `HxContact` and `HxContactEdit`) to handle server-side rendering and interactivity.
- A clean, minimal structure that supports server-side HTML updates without JavaScript.
## Features â¨
- **HTMX Integration**: Use HTMX to enable dynamic HTML updates without JavaScript, leveraging server-side interactions.
- **Carter Routing**: Minimal API routing using Carter makes defining API routes simple and clean.
- **Blazor Components**: Blazor components are used to encapsulate the UI, supporting easy reuse and testing.
- **.NET 8 Support**: Built to target .NET 8.0, ensuring compatibility with the latest features and enhancements.
- **Form Handling**: Use `hx-put` and `hx-get` to enable form binding and server-side state management.
## Installation âī¸
Install the template using the `dotnet new` command:
```bash
dotnet new install Atypical.MinimalHtmx.Templates
```
## Usage đ
Create a new project using the template:
```bash
dotnet new minimalhtmx -n YourProjectName
```
This command creates a new directory named `YourProjectName` with the template contents.
### Running the Project âļī¸
Once the project is created, navigate to the directory and run the application:
```bash
cd YourProjectName
dotnet run
```
The project will be available at `https://localhost:{PORT}` by default.
## Project Structure đī¸
- `Pages/Counter/PageCounter.razor`: Main Blazor component to display a counter.
- `Pages/Counter/PageCounter.razor.cs`: Defines API endpoints using Carter to handle GET and POST requests for counter data.
- `Pages/Counter/HxCounter.razor`: HTMX-enabled component that displays a counter.
- `Pages/Contact/PageContact.razor`: Main Blazor component to display a contact.
- `Pages/Contact/PageContact.razor.cs`: Defines API endpoints using Carter to handle GET and PUT requests for contact data.
- `Pages/Contact/HxContact.razor`: HTMX-enabled component that displays a contact's details.
- `Pages/Contact/HxContactEdit.razor`: HTMX-enabled edit form for contacts.
- `Store/AppState.cs`: Stores the state of the application, including contact details.
## Customization âī¸
### Adding New Routes â
To add new routes, modify the `AddRoutes` method in `PageContact.cs`. You can define new GET, POST, PUT, or DELETE endpoints using Carter's fluent routing API.
```csharp
public void AddRoutes(IEndpointRouteBuilder app)
{
var group = app.MapGroup("htmx/contact");
group.MapGet("/{Id:int}", HandleGet);
group.MapPut("/{Id:int}", HandlePut);
group.MapPost("/new", HandleCreateNew);
}
```
### Modifying Components đ ī¸
Components are located by feature in the `Pages` folder. You can edit `HxContact.razor` and `HxContactEdit.razor` to change the UI and behavior of the contact display and edit functionality.
### Using AppState đž
`AppState.cs` is used to store the state of your application, such as contact details. You can extend `AppState` to hold more data as your application grows.
## Contributing đ¤
Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request to the repository.
## License đ
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## About âšī¸
Developed by Philippe Matray, this template is aimed at developers looking for a minimal yet effective way to combine Blazor with HTMX and Carter, enabling interactive, server-driven web applications without relying on complex JavaScript frameworks.
---
# Quick Start Guide đ
1. **Install the Template**
```bash
dotnet new install Atypical.MinimalHtmx.Templates
```
2. **Create a New Solution**
```bash
mkdir HtmxDemo
cd HtmxDemo
dotnet new sln -n MyHtmxSolution
```
3. **Create a New MinimalHtmx Project**
```bash
dotnet new minimalhtmx -n MyHtmxApp
dotnet sln add MyHtmxApp
```
4. **Run the Application** âļī¸
Navigate to the project folder and run it:
```bash
cd MyHtmxApp
dotnet run
```
You should see the application running at `https://localhost:{PORT}`.