Htmx/docs/01-getting-started.md

Getting Started

This guide gets the solution running locally and explains what happens during startup.

What is in this solution

• Htmx.ApiDemo: ASP.NET Core app (Minimal API + generated HTMX endpoints)
• Htmx.SourceGenerator: Roslyn source generator that discovers .htmx files and generates endpoint mapping code
• Htmx.slnx: solution file at the repository root

Prerequisites

• .NET SDK 10.x (target framework is net10.0)
• Node.js + npm (used for Tailwind CSS compilation during build)
• MongoDB running locally on mongodb://localhost:27017

First-time setup

From the repository root:

cd Htmx.ApiDemo
npm install

Why this is required:

• The app build runs Tailwind via npx @tailwindcss/cli ... in a custom MSBuild target.
• Without npm install, build fails because the Tailwind CLI package is missing.

Run the app

From the repository root:

dotnet run --project Htmx.ApiDemo/Htmx.ApiDemo.csproj

Default local URL:

• http://localhost:5120

This comes from the launch profile in Htmx.ApiDemo/Properties/launchSettings.json.

Verify it works

1. Open http://localhost:5120
2. If you are not authenticated, middleware redirects to /login
3. Create an account at /register
4. Sign in and navigate the app

What startup config does

Htmx.ApiDemo/Program.cs configures:

• MongoDB DI and index initialization (EnsureIndexesAsync)
• Cookie authentication + authorization
• Antiforgery middleware
• AOT-friendly JSON resolver chain using AppJsonSerializerContext
• Endpoint registration via generated mapping call:
  • app.MapHtmxApiDemoEndpoints();

Build behavior worth knowing

• Tailwind CSS is compiled before build into Htmx.ApiDemo/wwwroot/css/output.css
• .htmx files are treated as generator inputs (<AdditionalFiles Include="**/*.htmx" />)
• AOT is enabled (<PublishAot>true</PublishAot>), so reflection-heavy patterns can break publish/runtime

Optional: publish as AOT

dotnet publish Htmx.ApiDemo/Htmx.ApiDemo.csproj -c Release

Use this early to catch AOT issues while developing features.

Troubleshooting

Build fails on Tailwind command

• Run npm install inside Htmx.ApiDemo
• Confirm node -v and npm -v are available

Mongo connection errors

• Confirm MongoDB is running on localhost:27017
• Confirm ConnectionStrings:DefaultConnection in Htmx.ApiDemo/appsettings.json

App keeps redirecting to login

• This is expected for unauthenticated routes
• Register at /register or sign in at /login