shaamilahmed/Enciphered.Blazor.UIComponents

Files

T

shaamilahmed 5668cf20d9 Added docs

2026-04-13 18:57:47 +05:00

5.2 KiB

Raw Permalink Blame History

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

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

dotnet add reference path/to/Enciphered.Blazor.UIComponents.csproj

Or, if published as a NuGet package:

dotnet add package Enciphered.Blazor.UIComponents

3. Install Tailwind CSS v4

From your solution root, initialize npm and install Tailwind:

npm init -y
npm install tailwindcss @tailwindcss/cli

Create Styles/app.css in your app project:

@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:

<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:

Stylesheet references — the library CSS and your app CSS
htmx CDN — loaded after blazor.web.js
JS module imports — initialize the library's interactive modules

<!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`

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:

@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:

@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:

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

5.2 KiB Raw Permalink Blame History