Documentations added

Co-authored-by: Copilot <copilot@github.com>
2026-05-04 19:57:48 +05:00
parent 40a7d9018c
commit ee8797c142
35 changed files with 6655 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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`