Table of Contents
Tailwind.MSBuild is a NuGet package that adds MSBuild tasks for building Tailwind CSS to your project. With this package, you can easily integrate Tailwind CSS into your .NET project and automatically generate your stylesheets as part of your project's build process. It will also download the Tailwind Standalone CLI so you don't need to have npm installed.
Disclaimer: This project is not affiliated with Tailwind Labs.
Use your preferred method of managing NuGet packages or use one of the following installation methods.
Install Tailwind.MSBuild using the NuGet Package Manager or with the following command in the Package Manager Console:
PM> Install-Package Tailwind.MSBuildYou can add a package reference using the following command when the .NET CLI is available:
> dotnet add package Tailwind.MSBuildYou can manually add the following lines to your .csproj file within an ItemGroup:
<PackageReference Include="Tailwind.MSBuild" Version="2.*">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>Note: You will need to build your project once in order to create the initial configuration when using this method.
Once installed, you can customize Tailwind by modifying the tailwind.input.css files in your configuration directory which defaults to $(MSBuildProjectDirectory)\Properties\. If the directory or file does not exist, a default configuration will be initialized for you the next time you build your project. By default this file will add your project directory as a source path for Tailwind to scan for class names. For detailed instructions on configuring Tailwind CSS, see the official Configuration guide.
Each time you build your project, a css file will be generated at $(MSBuildProjectDirectory)\wwwroot\css\tailwind.css. You can also customize your input and output file paths. For example, to set your input file to "src/styles/tailwind.css" and your output file to "wwwroot/css/tailwind.css", you can add the following to your .csproj file:
<PropertyGroup Label="Tailwind Properties">
<TailwindInputFile>$(MSBuildProjectDirectory)\src\styles\tailwind.css</TailwindInputFile>
<TailwindOutputFile>$(MSBuildProjectDirectory)\wwwroot\css\site.css</TailwindOutputFile>
</PropertyGroup>On Windows ARM64, the package prefers the release's native executable and uses x64 only when that release omits ARM64. A pinned release can reuse its cached native executable without a GitHub lookup. If the native executable is missing, the package checks the release metadata before using a cached x64 executable. On Windows ARM64, latest resolves to a concrete tag so the cache stays specific to that release.
Tailwind.MSBuild supports watch and hot-reload workflows by starting the Tailwind CLI in watch mode when it can detect a watch build.
Auto-detected scenarios:
- A build defaults to Tailwind watch when
BuildingInsideVisualStudioorDotNetWatchBuildis true, or when the build receivesDOTNET_WATCH=1orDOTNET_WATCH=true. This covers child builds fromdotnet watch buildanddotnet watch run --no-hot-reload. - With the .NET 10 SDK's hot reload workflow, plain
dotnet watch runstarts Tailwind during the watcher's project scan. In ASP.NET Core apps, the SDK can apply generated CSS changes in the open browser once its hot reload session is ready and the stylesheet is included as a watched static asset.
For SDKs without these watch signals, run dotnet watch run --property:TailwindWatch=true from your project directory. Set TailwindWatch=false to opt out of automatic watch mode.
On startup, Tailwind.MSBuild compiles the stylesheet before starting the watcher. The initial compilation reports errors to MSBuild. On Linux it tries xdg-terminal-exec, x-terminal-emulator, and known terminal emulators. Close the terminal window to stop its watcher. If no terminal can launch the CLI, the watcher runs with output redirected to a .log file beside the watch lock. The build prints the process ID and log path for that fallback.
If Linux auto-detection picks the wrong terminal, or you want to force a specific one, set TailwindTerminalExecutable to a supported terminal executable name or absolute path.
To avoid duplicate Tailwind CLI instances during watch builds, Tailwind.MSBuild tracks running processes in a lock file. You can override the lock file location with TailwindLockFile.
If you want to change any of the default settings Tailwind.MSBuild uses, you can override them by setting any of the following properties in your .csproj file.
| MSBuild Property Name | Default Value | Description |
|---|---|---|
| TailwindVersion | latest |
The version tag of the tailwind release to use. |
| TailwindInstallPath | $(MSBuildThisFileDirectory)..\cli\ |
The directory where the tailwindcss cli should be located. |
| TailwindConfigDir | $(MSBuildProjectDirectory)\Properties\ |
The directory containing the tailwind configuration files. |
| TailwindInputFile | tailwind.input.css |
The name of the input css file. |
| TailwindOutputFile | $(MSBuildProjectDirectory)\wwwroot\css\tailwind.css |
The path where the output css file will be located. |
| TailwindMinify | false for Debug builds, true for Release builds |
Whether the generated css should be minified or not. |
| TailwindWatch | true in detected watch builds, otherwise false |
Whether Tailwind runs in watch mode. |
| TailwindTerminalExecutable | `` | Optional Linux watch-mode terminal override. |
| TailwindLockFile | $(BaseIntermediateOutputPath)\tailwind-cli\watch.lock |
The path to the Tailwind CLI lock file. |
For the default install path,
$(MSBuildThisFileDirectory)expands to the directory where Tailwind.MSBuild.props was extracted to. This means the default value ofTailwindInstallPathis the equivilant of{NuGetPackageCache}\tailwind.msbuild\*VERSION*\cli\.
Here is a sample configuration that overrides every setting.
<PropertyGroup Label="Tailwind Properties">
<!-- Lock Tailwind Version -->
<TailwindVersion>v4.1.18</TailwindVersion>
<!-- Place Tailwind CLI in obj directory -->
<TailwindInstallPath>$(BaseIntermediateOutputPath)\tailwind-cli\</TailwindInstallPath>
<!-- Custom input and output file paths -->
<TailwindConfigDir>$(MSBuildProjectDirectory)\Tailwind\</TailwindConfigDir>
<!-- File names are relative to the TailwindConfigDir unless an absolute path is specified -->
<TailwindInputFile>input.css</TailwindInputFile>
<TailwindOutputFile>..\wwwroot\css\site.min.css</TailwindOutputFile>
<!-- Always minify the generated css -->
<TailwindMinify>true</TailwindMinify>
<!-- Force watch mode -->
<TailwindWatch>true</TailwindWatch>
<!-- Optional Linux terminal override -->
<TailwindTerminalExecutable>x-terminal-emulator</TailwindTerminalExecutable>
<!-- Override lock file location -->
<TailwindLockFile>$(BaseIntermediateOutputPath)\tailwind-cli\watch.lock</TailwindLockFile>
</PropertyGroup>Tailwind.MSBuild.targets defines a build target named BuildTailwind that runs before the BeforeBuild target. This target executes two tasks that Tailwind.MSBuild implements. The first task is GetTailwindCLI which returns the absolute path to the tailwind CLI to the build engine. The output is stored in a property which is then passed to BuildTailwindCSS as the value for the StandaloneCliPath parameter.
For advanced scenarios where you need to run the tasks during a different point in the build process, see the tables below for the parameters required for each task and the associated MSBuild Property passed by default. It is recommended to read Tailwind.MSBuild.targets as an example of how to properly invoke the MSBuild tasks.
| Task Parameter | MSBuild Property |
|---|---|
| Version | TailwindVersion |
| RootInstallPath | TailwindInstallPath |
<GetTailwindCLI Version="$(TailwindVersion)" RootInstallPath="$(TailwindInstallPath)">
<Output TaskParameter="StandaloneCliPath" PropertyName="StandaloneCliPath" />
</GetTailwindCLI>| Task Parameter | MSBuild Property |
|---|---|
| StandaloneCliPath | Output of GetTailwindCLI |
| ConfigDir | TailwindConfigDir |
| InputFile | TailwindInputFile |
| OutputFile | TailwindOutputFile |
| Minify | TailwindMinify |
| Watch | TailwindWatch |
| TerminalExecutable | TailwindTerminalExecutable |
| WatchLockFile | TailwindLockFile |
| ProjectDirectory | MSBuildProjectDirectory |
<BuildTailwindCSS StandaloneCliPath="$(StandaloneCliPath)"
ConfigDir="$(TailwindConfigDir)"
InputFile="$(TailwindInputFile)"
OutputFile="$(TailwindOutputFile)"
Minify="$(TailwindMinify)"
Watch="$(TailwindWatch)"
TerminalExecutable="$(TailwindTerminalExecutable)"
WatchLockFile="$(TailwindLockFile)"
ProjectDirectory="$(MSBuildProjectDirectory)">
<Output TaskParameter="GeneratedCssFile" PropertyName="GeneratedCssFile" />
</BuildTailwindCSS>Distributed under the MIT License. See LICENSE.md for more information.
Copyright © 2023 Michael Rasicci