Tailbreeze Documentation

How It Works

Tailbreeze downloads the official Tailwind CSS standalone CLI, caches it locally, and manages compilation automatically. No Node.js, npm, or manual CLI setup required.

Your Razor/Blazor Files --> Tailwind CLI (auto-downloaded) --> Compiled CSS
(.cshtml, .razor) (cached at %LOCALAPPDATA%) (app.css)

Quick Start

1. Configure Program.cs

using Tailbreeze.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddTailbreeze(); // One line

var app = builder.Build();
app.UseStaticFiles();
app.UseTailbreeze(); // Serves compiled CSS
app.MapRazorPages();
app.Run();

2. Add CSS to Layout

@addTagHelper *, Tailbreeze

Then add to your layout:

<head>
 <tailwind-link cdn-fallback="true" />
</head>

<!-- Or use a direct link -->
<link rel="stylesheet" href="/tailbreeze/app.css" />

<!-- Or Blazor component -->
<TailwindLink CdnFallback="true" />

Compilation Modes

Three modes to balance developer experience and output size.

Cdn (Default)

CDN in dev for instant access to all classes. CLI compiles optimized CSS in production. Best DX.

Full

Full Tailwind CSS without tree-shaking. No CLI needed. Larger output (~300KB) but zero configuration.

Optimized

Traditional CLI watch mode in dev, tree-shaken output in prod. Smallest CSS (~10-50KB).

builder.Services.AddTailbreeze(); // Default: Cdn mode
builder.Services.AddTailbreeze(opts => opts.Mode = TailbreezeMode.Full);
builder.Services.AddTailbreeze(opts => opts.Mode = TailbreezeMode.Optimized);

Configuration

Property	Default	Description
TailwindVersion	"latest"	Version: "latest", "3", "4", "3.4.17", "4.0.0"
Mode	Cdn	Cdn, Full, or Optimized
InputCssPath	Styles/app.css	Input CSS file path
OutputCssPath	css/app.css	Output path relative to wwwroot
EnableHotReload	true	Watch mode in development
MinifyCss	null	null = false in dev, true in prod
AutoInstallCli	true	Auto-download CLI if missing
ServePath	/tailbreeze/app.css	URL for middleware to serve CSS
CliStartupTimeoutSeconds	60	Timeout for CLI to produce output

Full Configuration Example

builder.Services.AddTailbreeze(options =>
{
 options.TailwindVersion = "4";
 options.Mode = TailbreezeMode.Cdn;
 options.InputCssPath = "Styles/app.css";
 options.OutputCssPath = "css/app.css";
 options.EnableHotReload = true;
 options.MinifyCss = null; // Auto: false in dev, true in prod
 options.AutoInstallCli = true;
 options.ContentPaths = new List<string>
 {
 "./Pages/**/*.{cshtml,razor}",
 "./Components/**/*.razor"
 };
});

Project Type Support

Razor Pages / MVC

Use runtime package with tag helper <tailwind-link />. Full hot reload support.

Blazor Server / Web App

Use runtime package with <TailwindLink /> component or direct link.

Blazor WebAssembly

Build package only (Noundry.Tailbreeze.Build). Use css/app.css directly.

Via appsettings.json

Bind configuration from JSON with AddTailbreeze(builder.Configuration).

MSBuild Integration

The build package adds compile-time CSS generation via MSBuild targets.

<PropertyGroup>
 <TailbreezeTailwindVersion>4</TailbreezeTailwindVersion>
 <TailbreezeInputCss>Styles/app.css</TailbreezeInputCss>
 <TailbreezeOutputCss>css/app.css</TailbreezeOutputCss>
 <TailbreezeMinify>false</TailbreezeMinify>
 <TailbreezeMinifyOnPublish>true</TailbreezeMinifyOnPublish>
 <TailbreezeCompileOnBuild>true</TailbreezeCompileOnBuild>
</PropertyGroup>

Component Library Integration

Tailbreeze automatically detects component libraries (like Noundry.UI) that ship class list files, ensuring all component styles are included in the compiled CSS.

// Automatic - no configuration needed!
builder.Services.AddNoundryUI();
builder.Services.AddTailbreeze(); // Detects noundry-ui-classes.json

// Or with explicit paths for custom libraries
builder.Services.AddTailbreeze(opts =>
{
 opts.AutoDetectComponentLibraries = true;
 opts.ComponentLibraryClassFiles = new List<string>
 {
 "./my-component-classes.json"
 };
});

Tailwind Version Differences

Aspect	Tailwind v4 (default)	Tailwind v3
CSS Directive	@import "tailwindcss";	@tailwind base/components/utilities;
Config Syntax	export default { }	module.exports = { }
Custom Classes	Direct in CSS	Inside @layer components { }
Download	Latest from GitHub	Fixed at v3.4.17 (LTS)

Tailbreeze