Project Setup

BlazorNova

☰

☰ Menu

Getting Started

Installation

Project Setup

Source Generator

Core Concepts

Surface System

Color Palette

Fluent CSS API

Style Overrides

CSS Precedence

BlazorNova Classes

Components

After installing the packages, four short steps wire BlazorNova into your application: create a config class, register the services, add the init component, and link the generated CSS and JS files.

1 — Create a Config Class

Create a class that inherits BlazorNovaConfig and set RelativeOutputDirectory to the project-relative path where the source generator should write generated files (CSS and JS). This is how the generator knows where to output.

Optionally override LightPalette and DarkPalette to supply your own brand colours. If you omit these, the default BlazorNova palette is used.

csharp

using BlazorNovaGenerator;

public class MyAppConfig : BlazorNovaConfig
{
    // Directory is relative to the project root.
    // The generator writes generated.css and generated-theme.js here.
    public override string RelativeOutputDirectory => "/wwwroot/generated";

    // Optional: choose a font preset (default is SystemSans).
    // public override BnFontFamily FontFamily => BnFontFamily.Serif;

    // Or use a fully custom font stack:
    // public override BnFontFamily FontFamily => BnFontFamily.Custom;
    // public override string CustomFontFamily => "'Inter', sans-serif";

    // Optional: supply your own brand palette.
    // public override ThemePalette LightPalette => new MyLightPalette();
    // public override ThemePalette DarkPalette  => new MyDarkPalette();
}

2 — Create the Output Folder

Create a generated folder inside wwwroot. The source generator will write generated.css and generated-theme.js into this directory on every build. The folder must exist before your first build.

bash

# Windows
mkdir wwwroot\generated

# macOS / Linux
mkdir -p wwwroot/generated

3 — Register in Program.cs

Call AddBlazorNova<T>() with your config type. This registers BlazorNovaConfig, BlazorNovaEngine (theme + popup manager), and BnJSService (JS interop wrapper) as scoped services.

csharp

// Program.cs
builder.Services.AddBlazorNova<MyAppConfig>();

4 — Add BlazorNovaInit

Wrap your Router inside <BlazorNovaInit> in Routes.razor (Blazor Server) or App.razor (WASM). This component:

Detects the user's system colour scheme (light / dark) via JS interop
Listens for prefers-color-scheme changes and re-renders accordingly
Hosts the modal and popup render roots that all BnPopup and modal components use
Prevents content flash by hiding children until the theme engine is ready

razor

@* Routes.razor (Blazor Server) or App.razor (WASM) *@
<BlazorNovaInit>
    <Router AppAssembly="typeof(Program).Assembly">
        <Found Context="routeData">
            <RouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)" />
        </Found>
    </Router>
</BlazorNovaInit>

5 — Link CSS and JS in App.razor

Add the generated stylesheet to <head> and the BlazorNova JS to the end of <body>. If you are using BlazorNovaComponents, also include its JS file.

html

<head>
    <!-- Generated CSS — updated on every build -->
    <link rel="stylesheet" href="generated/generated.css" />

    <!-- Theme init — prevents dark-mode flash (also generated on build) -->
    <script src="generated/generated-theme.js"></script>
</head>
<body>
    <Routes @rendermode="InteractiveServer" />
    <script src="_framework/blazor.web.js"></script>

    <!-- BlazorNovaUI runtime (theme switching, popups, JS interop) -->
    <script src="_content/BlazorNovaUI/BlazorNova.js"></script>

    <!-- BlazorNovaComponents runtime (if installed) -->
    <script src="_content/BlazorNovaComponents/BnComponents.js"></script>
</body>