Package icon

Noundry.Tailbreeze 1.2.2

by Tailbreeze Contributors

Tailbreeze

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

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(); // or AddControllersWithViews(), AddRazorComponents()
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" />

Or use the TailwindLink component (requires @using Tailbreeze.Components in _Imports.razor):

<TailwindLink CdnFallback="true" />

3. Run

dotnet run

On first run, Tailbreeze will:

  1. Download the Tailwind CLI (~15MB) to %LOCALAPPDATA%/Tailbreeze/cli/
  2. Create Styles/app.css with Tailwind directives
  3. Create tailwind.config.js with auto-detected content paths
  4. Start watch mode to compile CSS on file changes

Configuration

Via Code

builder.Services.AddTailbreeze(options =>
{
    options.TailwindVersion = "4";           // "latest", "3", "4", or "3.4.17"
    options.InputCssPath = "Styles/app.css";
    options.OutputCssPath = "css/app.css";
    options.ConfigPath = "tailwind.config.js";
    options.EnableHotReload = true;
    options.AutoInstallCli = true;
});

Via appsettings.json

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

builder.Services.AddTailbreeze(builder.Configuration);

Configuration Options

Option Default Description
TailwindVersion "latest" Version to use: "latest", "3", "4", or specific like "3.4.17"
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 CSS output (default: false in dev, true in production)
AutoInstallCli true Auto-download CLI if missing
ServePath "/tailbreeze/app.css" URL path for serving CSS
ServeViaMiddleware true Serve CSS through middleware
UseCdnFallback null Fall back to CDN if CLI fails (default: true in dev)
CliDownloadUrl null Custom URL for CLI download (for mirrors/firewalls)
ContentPaths [] Custom content paths (auto-detected if empty)
AdditionalArguments null Additional arguments to pass to Tailwind CLI
CliStartupTimeoutSeconds 60 Timeout for CLI startup in seconds (minimum: 10)

Version Support

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

How Files Are Generated

Input CSS (Styles/app.css)

Tailwind v4:

@import "tailwindcss";

Tailwind v3:

@tailwind base;
@tailwind components;
@tailwind utilities;

Config File (tailwind.config.js)

Tailwind v4:

export default {
  content: [
    "./Pages/**/*.{cshtml,razor}",
    "./Views/**/*.cshtml",
    "./Components/**/*.{cshtml,razor}"
  ],
}

Tailwind v3:

module.exports = {
  content: [
    "./Pages/**/*.{cshtml,razor}",
    "./Views/**/*.cshtml",
    "./Components/**/*.{cshtml,razor}"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Custom Download URL

For corporate environments with restricted internet access:

{
  "Tailbreeze": {
    "CliDownloadUrl": "https://internal-mirror.company.com/tailwindcss-{os}-{arch}{extension}"
  }
}

Placeholders:

  • {os} - windows, linux, or macos
  • {arch} - x64 or arm64
  • {version} - The configured version
  • {extension} - .exe on Windows, empty otherwise

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

Production Builds

In production, the CSS is compiled once during publish. The watch mode only runs in Development environment.

For MSBuild integration (compile during dotnet publish), add the Noundry.Tailbreeze.Build package:

dotnet add package Noundry.Tailbreeze.Build

Troubleshooting

CSS not updating

  1. Check the console for Tailwind CLI output
  2. Verify Styles/app.css exists
  3. Check tailwind.config.js has correct content paths

CLI download fails

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

Classes not being detected

  1. Check tailwind.config.js content paths include your file extensions
  2. Ensure you're using complete class names (not string concatenation)

Architecture

src/Tailbreeze/
├── Extensions/
│   ├── ServiceCollectionExtensions.cs   # AddTailbreeze()
│   └── ApplicationBuilderExtensions.cs  # UseTailbreeze()
├── Services/
│   ├── ITailwindCliService.cs           # CLI management interface
│   ├── TailwindCliService.cs            # Downloads and executes CLI
│   └── TailwindHostedService.cs         # Runs watch mode in dev
├── Middleware/
│   └── TailwindMiddleware.cs            # Serves compiled CSS
├── TagHelpers/
│   └── TailwindLinkTagHelper.cs         # <tailwind-link />
├── Components/
│   └── TailwindLink.razor               # Blazor component
├── TailbreezeOptions.cs                 # Configuration
└── TailwindVersion.cs                   # Version parsing

License

MIT License - see LICENSE file.

Inspired by tailwind-dotnet by Kalleby Santos.

No packages depend on Noundry.Tailbreeze.

See CHANGELOG.md for release notes.

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

Info

Statistics

Total Downloads
29
Current Version Downloads
12

Authors

Tailbreeze Contributors