93 lines
2.5 KiB
Markdown
93 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`
|