210 lines
5.2 KiB
Markdown
210 lines
5.2 KiB
Markdown
# Getting Started
|
|
|
|
This guide walks you through adding **Enciphered.Blazor.UIComponents** to a new or existing Blazor Web App and building a fully static SSR application with htmx-powered form validation.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
| Tool | Version |
|
|
|---|---|
|
|
| .NET SDK | 9.0+ |
|
|
| Node.js | 18+ (for Tailwind CSS CLI) |
|
|
|
|
---
|
|
|
|
## 1. Create a Blazor Web App
|
|
|
|
```bash
|
|
dotnet new blazor -n MyApp --interactivity None
|
|
cd MyApp
|
|
```
|
|
|
|
> The `--interactivity None` flag creates a pure static SSR app — no SignalR or WebAssembly.
|
|
|
|
---
|
|
|
|
## 2. Install the Library
|
|
|
|
```bash
|
|
dotnet add reference path/to/Enciphered.Blazor.UIComponents.csproj
|
|
```
|
|
|
|
Or, if published as a NuGet package:
|
|
|
|
```bash
|
|
dotnet add package Enciphered.Blazor.UIComponents
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Install Tailwind CSS v4
|
|
|
|
From your solution root, initialize npm and install Tailwind:
|
|
|
|
```bash
|
|
npm init -y
|
|
npm install tailwindcss @tailwindcss/cli
|
|
```
|
|
|
|
Create `Styles/app.css` in your app project:
|
|
|
|
```css
|
|
@import "tailwindcss";
|
|
|
|
@custom-variant dark (&:where(.dark, .dark *));
|
|
```
|
|
|
|
Add the library's design tokens by importing or copying the token definitions from `Enciphered.Blazor.UIComponents/Styles/app.css`. At minimum you need the `:root` and `.dark` token blocks and the `@theme` mapping.
|
|
|
|
Add a build step to your `.csproj`:
|
|
|
|
```xml
|
|
<Target Name="TailwindBuild" BeforeTargets="Build">
|
|
<Exec Command="npx @tailwindcss/cli -i Styles/app.css -o wwwroot/css/app.css --minify" />
|
|
</Target>
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Configure `App.razor`
|
|
|
|
Your root `App.razor` needs three things:
|
|
|
|
1. **Stylesheet references** — the library CSS and your app CSS
|
|
2. **htmx CDN** — loaded after `blazor.web.js`
|
|
3. **JS module imports** — initialize the library's interactive modules
|
|
|
|
```razor
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<base href="/" />
|
|
|
|
<!-- Dark-mode bootstrap: prevents flash of wrong theme -->
|
|
<script>
|
|
(function () {
|
|
try {
|
|
if (localStorage.getItem('theme') === 'dark')
|
|
document.documentElement.classList.add('dark');
|
|
} catch (e) { }
|
|
})();
|
|
</script>
|
|
|
|
<!-- Library stylesheet (design tokens + component styles) -->
|
|
<link rel="stylesheet" href="_content/Enciphered.Blazor.UIComponents/css/app.css" />
|
|
|
|
<!-- Your app stylesheet -->
|
|
<link rel="stylesheet" href="css/app.css" />
|
|
|
|
<HeadOutlet />
|
|
</head>
|
|
<body class="min-h-svh antialiased bg-background text-foreground">
|
|
<Routes />
|
|
|
|
<!-- Blazor framework script -->
|
|
<script src="_framework/blazor.web.js"></script>
|
|
|
|
<!-- htmx (required for form validation/submission) -->
|
|
<script src="https://unpkg.com/htmx.org@2.0.4"
|
|
integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+"
|
|
crossorigin="anonymous"></script>
|
|
|
|
<!-- Initialize library JS modules -->
|
|
<script type="module">
|
|
import { init as initDarkMode } from '/_content/Enciphered.Blazor.UIComponents/js/darkmode.js';
|
|
import { init as initSidebar } from '/_content/Enciphered.Blazor.UIComponents/js/sidebar.js';
|
|
import { init as initForms } from '/_content/Enciphered.Blazor.UIComponents/js/forms.js';
|
|
initDarkMode();
|
|
initSidebar();
|
|
initForms();
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
> **Note**: Only import the modules you need. If you don't use the sidebar, skip `initSidebar()`. If you don't use forms, skip `initForms()`. If you don't need dark mode, skip `initDarkMode()` and the bootstrap script.
|
|
|
|
---
|
|
|
|
## 5. Configure `Program.cs`
|
|
|
|
Register Razor Components and map the library assembly:
|
|
|
|
```csharp
|
|
var builder = WebApplication.CreateBuilder(args);
|
|
|
|
builder.Services.AddRazorComponents();
|
|
builder.Services.AddAntiforgery();
|
|
|
|
var app = builder.Build();
|
|
|
|
app.UseHttpsRedirection();
|
|
app.UseAntiforgery();
|
|
app.MapStaticAssets();
|
|
|
|
app.MapRazorComponents<App>()
|
|
.AddAdditionalAssemblies(
|
|
typeof(Enciphered.Blazor.UIComponents.SidebarProvider).Assembly);
|
|
|
|
app.Run();
|
|
```
|
|
|
|
> The `AddAdditionalAssemblies` call registers the library's components for routing discovery.
|
|
|
|
---
|
|
|
|
## 6. Add `_Imports.razor`
|
|
|
|
In your app's `Components/_Imports.razor`, add:
|
|
|
|
```razor
|
|
@using Enciphered.Blazor.UIComponents
|
|
```
|
|
|
|
This makes all library components available without per-file `@using` directives.
|
|
|
|
---
|
|
|
|
## 7. Verify the Setup
|
|
|
|
Create a simple page to test:
|
|
|
|
```razor
|
|
@page "/test"
|
|
|
|
<Card>
|
|
<CardHeader>
|
|
<CardTitle>It Works!</CardTitle>
|
|
<CardDescription>The library is installed correctly.</CardDescription>
|
|
</CardHeader>
|
|
<CardContent>
|
|
<p>If you can see this styled card, everything is set up.</p>
|
|
</CardContent>
|
|
<CardFooter>
|
|
<Button>Click Me</Button>
|
|
</CardFooter>
|
|
</Card>
|
|
```
|
|
|
|
Run the app:
|
|
|
|
```bash
|
|
dotnet run
|
|
```
|
|
|
|
You should see a styled card with a button. If the styles aren't applied, verify:
|
|
- The Tailwind build step ran (check `wwwroot/css/app.css` exists)
|
|
- The stylesheet links in `App.razor` are correct
|
|
- The design tokens are present in your `Styles/app.css`
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- [Set up a sidebar layout →](components/sidebar.md)
|
|
- [Add form validation with htmx →](forms/validation.md)
|
|
- [Browse all components →](components/button.md)
|