Skip to content

ServerIntegration

Jump to bottom
Edgar Mesquita edited this page Feb 9, 2026 · 8 revisions

Server Integration

eQuantic.UI integrates with ASP.NET Core through a fluent API for service registration, middleware configuration, and HTML shell customization.

Quick Start

var builder = WebApplication.CreateBuilder(args);

// Register services
builder.Services.AddTailwind();              // Theme (optional)
builder.Services.AddLucideIcons();           // Icons (optional)
builder.Services.AddChartJs();               // Charts (optional)
builder.Services.AddApexCharts();            // Charts (optional)

builder.Services.AddUI(options =>
{
    options.ScanAssembly(typeof(Program).Assembly)
           .WithSsr()
           .ConfigureHtmlShell(shell =>
           {
               shell.SetTitle("My App")
                    .SetHtmlClass("dark")
                    .AddHeadTag("<meta name=\"theme-color\" content=\"#3b82f6\">");
           });
});

var app = builder.Build();

app.UseStaticFiles();
app.UseServerActions();                      // Server Actions middleware
app.UseTailwind();                           // Tailwind CSS endpoints (optional)
app.UseChartJs();                            // Chart.js CDN endpoints (optional)
app.UseApexCharts();                         // ApexCharts CDN endpoints (optional)
app.MapUI();                                 // SPA routing

app.Run();

AddUI

AddUI() is the main entry point that registers all core services:

builder.Services.AddUI(options => { ... });

What it registers:

  • UIOptions (singleton) - Configuration
  • IServerActionRegistry - Scans assemblies for [ServerAction] methods
  • IServerActionAuthorizationService - Authorization for server actions
  • IServerRenderingService - SSR rendering engine
  • IAppTheme - Default eQuantic theme (overridden by AddTailwind())
  • IComponentAssetProvider<T> - Auto-scanned from assemblies (see Assets)
  • SignalR services

UIOptions

Fluent configuration API for the UI framework.

ScanAssembly

Scans an assembly for [Page] components, [ServerAction] methods, and IComponentAssetProvider<T> implementations.

options.ScanAssembly(typeof(Program).Assembly);

Multiple assemblies can be scanned:

options.ScanAssembly(typeof(Program).Assembly)
       .ScanAssembly(typeof(SharedComponents).Assembly);

WithSsr

Enables or disables Server-Side Rendering globally. Default is true.

options.WithSsr();           // Enable (default)
options.WithSsr(false);      // Disable

Individual pages can opt-out:

[Page("/interactive", DisableSsr = true)]
public class InteractivePage : StatefulComponent { }

WithAssetProvider<T>

Explicitly registers an IComponentAssetProvider<T> implementation. Useful for providers from external assemblies not covered by ScanAssembly.

options.WithAssetProvider<ChartJsAssetProvider>();

See Assets for details on the asset provider system.

ConfigureHtmlShell

Configures the HTML template that wraps all pages.

options.ConfigureHtmlShell(shell =>
{
    shell.SetTitle("My App")
         .SetHtmlClass("dark")
         .SetBaseStyles("body { margin: 0; }")
         .AddHeadTag("<link rel=\"icon\" href=\"/favicon.ico\">")
         .AddHeadTag("<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">");
});

Properties

Property Type Default Description
EnableSsr bool true Global SSR toggle
EnableDefaultCss bool true Inject default eQuantic CSS (set false with Tailwind)
HtmlShell HtmlShellOptions - HTML template configuration

HtmlShellOptions

Method Description
SetTitle(string) Page <title>
SetHtmlClass(string) Class on <html> element (e.g., "dark")
SetBaseStyles(string) Base <style> block
AddHeadTag(string) Raw HTML tag injected into <head>

Middleware

UseServerActions

Registers the Server Actions middleware for handling RPC calls from the browser.

app.UseServerActions();

Server Actions are methods marked with [ServerAction] that execute server-side and return results to the client:

[ServerAction]
public async Task<List<Todo>> LoadTodos()
{
    using var db = new AppDbContext();
    return await db.Todos.ToListAsync();
}

MapUI

Maps SPA routing — serves the HTML shell for all unmatched routes, enabling client-side navigation.

app.MapUI();

UseTailwind

Enables Tailwind CSS dynamic endpoints (theme scripts, dark mode scripts). Must be called after AddTailwind().

builder.Services.AddTailwind();   // Services
app.UseTailwind();                // Middleware

UseChartJs / UseApexCharts

Enables CDN script endpoints for chart libraries.

builder.Services.AddChartJs();    // Services
app.UseChartJs();                 // Middleware (optional version override)

builder.Services.AddApexCharts();
app.UseApexCharts();

Server-Side Rendering (SSR)

When SSR is enabled, the framework:

  1. Finds the matching [Page] component for the route
  2. Creates the component instance (with DI support)
  3. Collects asset dependencies (see Assets)
  4. Collects SEO metadata (see below)
  5. Renders the component tree to HTML
  6. Serializes state for client-side hydration
  7. Serves the complete HTML page

SEO & Metadata

Components implement IHandleMetadata for dynamic SEO:

public class BlogPost : StatelessComponent, IHandleMetadata
{
    public void ConfigureMetadata(SeoBuilder seo)
    {
        seo.Title("Blog Post Title")
           .Description("A summary of the post...")
           .Canonical("https://example.com/blog/post")
           .OpenGraph("type", "article")
           .Twitter("card", "summary_large_image");
    }
}

SeoBuilder methods:

Method Description
Title(string) Page title
Description(string) Meta description
Canonical(string) Canonical URL
Image(string, string?) OG image
Keywords(string) Meta keywords
Robots(bool, bool) Index/follow directives
OpenGraph(string, string) OG property
Twitter(string, string) Twitter card property

Registration Order

The recommended order for service registration:

// 1. Theme (must be before AddUI for SSR to use correct theme)
builder.Services.AddTailwind();

// 2. Icons
builder.Services.AddLucideIcons();

// 3. Charts
builder.Services.AddChartJs();
builder.Services.AddApexCharts();

// 4. Core UI (scans assemblies, auto-registers asset providers)
builder.Services.AddUI(options => { ... });

Middleware order:

app.UseStaticFiles();
app.UseRouting();
app.UseServerActions();    // Before MapUI
app.UseTailwind();         // Theme endpoints
app.UseChartJs();          // Chart CDN
app.UseApexCharts();       // Chart CDN
app.MapUI();               // SPA fallback (last)

Clone this wiki locally