Package icon

Noundry.Tailbreeze.Build 1.3.0

by Tailbreeze Contributors

Tailbreeze

A .NET library for integrating Tailwind CSS into ASP.NET applications with zero Node.js dependency.

Features

  • Zero Node.js - Uses official Tailwind CSS standalone CLI
  • Three Modes - CDN (best DX), Full (no CLI), or Optimized (smallest output)
  • Auto-detection - Finds your Razor/Blazor files automatically
  • Component Libraries - Auto-integrates with Noundry.UI and similar libraries
  • Hot Reload - CSS recompiles on file changes during development
  • Production Ready - Minified, tree-shaken CSS for production builds

How It Works

Tailbreeze downloads the official Tailwind CSS standalone CLI from GitHub releases and manages it locally. During development, it runs the CLI in watch mode to automatically recompile CSS when your Razor/Blazor files change.

Your .cshtml/.razor files  -->  Tailwind CLI (watch mode)  -->  compiled CSS  -->  browser

Requirements

  • .NET 8.0, 9.0, or 10.0
  • Windows, macOS, or Linux (x64 or arm64)
  • Internet connection (first run only, to download CLI)

Installation

dotnet add package Noundry.Tailbreeze

Quick Start

1. Add to Program.cs

using Tailbreeze.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddTailbreeze();

var app = builder.Build();

app.UseStaticFiles();
app.UseTailbreeze();
app.MapRazorPages();

app.Run();

2. Add to your layout

Razor Pages / MVC (_Layout.cshtml):

@addTagHelper *, Tailbreeze

<!DOCTYPE html>
<html>
<head>
    <tailwind-link />
</head>
<body>
    @RenderBody()
</body>
</html>

Blazor (App.razor):

<link rel="stylesheet" href="/tailbreeze/app.css" />

3. Run

dotnet run

That's it! On first run, Tailbreeze automatically:

  1. Downloads the Tailwind CLI (~15MB) to local cache
  2. Creates Styles/app.css with Tailwind directives
  3. Creates tailwind.config.js with auto-detected content paths
  4. Starts watch mode to compile CSS on file changes

Compilation Modes

Tailbreeze supports three compilation modes to optimize for different scenarios:

Mode Development Production Best For
Cdn (default) Uses cdn.tailwindcss.com CLI compiles optimized CSS Most projects
Full CDN fallback Full CSS (~300KB gzip) Simple apps, offline
Optimized CLI watch mode CLI with tree-shaking Performance-critical 
// CDN mode (default) - best developer experience
builder.Services.AddTailbreeze();

// Full mode - no CLI dependency, larger output
builder.Services.AddTailbreeze(opts => opts.Mode = TailbreezeMode.Full);

// Optimized mode - traditional CLI behavior, smallest output
builder.Services.AddTailbreeze(opts => opts.Mode = TailbreezeMode.Optimized);

Why CDN Mode is Default

  • Instant startup - No CLI download or compilation delay
  • All classes available - Every Tailwind class works immediately
  • Production optimized - CLI still compiles tree-shaken CSS for production
  • Best DX - Just write code, no waiting

Component Library Integration

Tailbreeze automatically detects and includes CSS classes from component libraries like Noundry.UI.

How It Works

  1. When you install Noundry.UI, its MSBuild target copies a safelist file to your project
  2. Tailbreeze detects the safelist and adds it to Tailwind's content paths
  3. All component classes are included in compiled CSS automatically

No manual configuration required!

// Just add both packages - integration is automatic
builder.Services.AddNoundryUI();
builder.Services.AddTailbreeze();

Supported Files (Auto-detected)

File Description
noundry-ui-safelist.html Noundry.UI component classes
noundry-ui-classes.json JSON format class list
*-classes.json Other component libraries

Configuration

Via Code

builder.Services.AddTailbreeze(options =>
{
    options.Mode = TailbreezeMode.Cdn;        // Cdn, Full, or Optimized
    options.TailwindVersion = "4";            // "latest", "3", "4", or "3.4.17"
    options.InputCssPath = "Styles/app.css";
    options.OutputCssPath = "css/app.css";
    options.EnableHotReload = true;
    options.AutoDetectComponentLibraries = true;
});

Via appsettings.json

{
  "Tailbreeze": {
    "Mode": "Cdn",
    "TailwindVersion": "4",
    "InputCssPath": "Styles/app.css",
    "OutputCssPath": "css/app.css",
    "EnableHotReload": true
  }
}

Configuration Options

Option Default Description
Mode Cdn Compilation mode: Cdn, Full, or Optimized
AutoDetectComponentLibraries true Auto-detect component library safelist files
ComponentLibraryClassFiles [] Explicit paths to class list files
TailwindVersion "latest" Version: "latest", "3", "4", or specific
InputCssPath "Styles/app.css" Source CSS file (relative to project root)
OutputCssPath "css/app.css" Output CSS file (relative to wwwroot)
ConfigPath "tailwind.config.js" Tailwind config file path
EnableHotReload true Enable watch mode in development
MinifyCss null Minify output (default: false in dev, true in prod)
AutoInstallCli true Auto-download CLI if missing
ServePath "/tailbreeze/app.css" URL path for serving CSS
UseCdnFallback null Fall back to CDN if CLI fails
ContentPaths [] Custom content paths (auto-detected if empty)

Version Support

TailwindVersion Downloads CSS Syntax
"latest" Latest stable from GitHub v4 (@import "tailwindcss")
"4" Latest v4.x stable v4 (@import "tailwindcss")
"3" v3.4.17 (LTS) v3 (@tailwind base/components/utilities)

Production Builds

For MSBuild integration (compile during dotnet build or dotnet publish):

dotnet add package Noundry.Tailbreeze.Build

The build package automatically:

  • Detects component library safelist files
  • Generates optimized CSS during build
  • Minifies CSS during publish

CLI Storage Location

The Tailwind CLI is downloaded once and cached at:

  • Windows: %LOCALAPPDATA%\Tailbreeze\cli\{version}\tailwindcss.exe
  • macOS/Linux: ~/.local/share/Tailbreeze/cli/{version}/tailwindcss

Troubleshooting

Classes not being applied

  1. In CDN mode: All classes should work - check browser console
  2. In Optimized mode: Check tailwind.config.js content paths
  3. Component library: Verify safelist file exists in project root

CLI download fails

  1. Check internet connectivity
  2. Try setting a custom CliDownloadUrl for corporate mirrors
  3. Manually download from https://github.com/tailwindlabs/tailwindcss/releases

License

MIT License - see LICENSE file.

Inspired by tailwind-dotnet by Kalleby Santos.

This package has no dependencies.

No packages depend on Noundry.Tailbreeze.Build.

See CHANGELOG.md for release notes.

Version Downloads Last Updated
1.3.0 Current 9 1/8/2026
1.2.2 14 12/30/2025

Info

Statistics

Total Downloads
23
Current Version Downloads
9

Authors

Tailbreeze Contributors