Tailwind CSS Setup Guide for Blazor

This guide shows you how to set up Tailwind CSS for a new Blazor project using the same approach as the ShellUI CLI tool.

Installation Methods Comparison

Method	Setup Speed	Build Speed	Production Ready	Node.js Required
Play CDN	⚡ Fastest (instant)	None	❌ No	No
Standalone	Fast (one-time download)	Fast	✅ Yes	No
npm	Medium (npm install)	Fast	✅ Yes	Yes

Play CDN — Add one script tag, zero build step. Dev/demo only — serves full Tailwind (~500KB+), not optimized for production.
Standalone — Downloads a single binary (~10MB) once. No Node.js. Recommended for Blazor — fast builds, production-ready.
npm — Full Node.js workflow. Best if you already use npm or need plugins.

TL;DR: Standalone is the fastest production option for .NET/Blazor. Use CDN only for quick prototypes.

Prerequisites

.NET 9.0 SDK
A Blazor project (new or existing)

Method 1: Using ShellUI CLI (Recommended)

The easiest way to set up Tailwind CSS in a Blazor project is using the ShellUI CLI tool, which handles everything automatically.

Step 1: Install ShellUI CLI

# Install globally
dotnet tool install -g ShellUI.CLI

# Or install from local source (if testing locally)
dotnet tool install -g ShellUI.CLI --add-source ./src/ShellUI.CLI/bin/Release

Step 2: Initialize in your project

# Navigate to your Blazor project
cd path/to/your/blazor-project

# Initialize ShellUI (this sets up Tailwind automatically)
dotnet shellui init

This command automatically:

✅ Downloads Tailwind CSS CLI (standalone, no Node.js required)
✅ Creates CSS files with design tokens
✅ Sets up MSBuild integration for auto-building
✅ Creates component folders
✅ Builds Tailwind CSS

Step 3: Add components (optional)

# Add specific components
dotnet shellui add button input card

# List all available components
dotnet shellui list

Method 2: Manual Setup (Alternative)

If you prefer to set up Tailwind CSS manually or want to understand the process:

Step 1: Download Tailwind CSS CLI

# Download Tailwind CLI (standalone, no Node.js required)
# Windows
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-windows-x64.exe

# Linux
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64

# macOS
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-macos-x64

# Make executable (Linux/macOS)
chmod +x tailwindcss-*

Step 2: Create CSS files

Create wwwroot/input.css:

@import "tailwindcss";

Note: This creates a minimal Tailwind setup. Add your custom CSS variables, colors, and design tokens as needed.

Create wwwroot/app.css (placeholder, will be generated):

/* This file will be generated by Tailwind CSS */

Step 3: Create Tailwind configuration

Create tailwind.config.js:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './Components/**/*.{razor,html,cshtml}',
    './Pages/**/*.{razor,html,cshtml}',
    './wwwroot/**/*.html',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))',
        },
        destructive: {
          DEFAULT: 'hsl(var(--destructive))',
          foreground: 'hsl(var(--destructive-foreground))',
        },
        muted: {
          DEFAULT: 'hsl(var(--muted))',
          foreground: 'hsl(var(--muted-foreground))',
        },
        accent: {
          DEFAULT: 'hsl(var(--accent))',
          foreground: 'hsl(var(--accent-foreground))',
        },
        popover: {
          DEFAULT: 'hsl(var(--popover))',
          foreground: 'hsl(var(--popover-foreground))',
        },
        card: {
          DEFAULT: 'hsl(var(--card))',
          foreground: 'hsl(var(--card-foreground))',
        },
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
    },
  },
  plugins: [],
}

Step 4: Set up MSBuild integration

Create Build/ShellUI.targets:

<?xml version="1.0" encoding="utf-8"?>
<Project>
  <PropertyGroup>
    <ShellUIBinPath Condition="'$(ShellUIBinPath)' == ''">$(MSBuildProjectDirectory)\.shellui\bin</ShellUIBinPath>
    <TailwindExecutable Condition="'$(OS)' == 'Windows_NT'">$(ShellUIBinPath)\tailwindcss.exe</TailwindExecutable>
    <TailwindExecutable Condition="'$(OS)' != 'Windows_NT'">$(ShellUIBinPath)/tailwindcss</TailwindExecutable>
    <TailwindInputCss Condition="'$(TailwindInputCss)' == ''">$(MSBuildProjectDirectory)\wwwroot\input.css</TailwindInputCss>
    <TailwindOutputCss Condition="'$(TailwindOutputCss)' == ''">$(MSBuildProjectDirectory)\wwwroot\app.css</TailwindOutputCss>
    <TailwindMinify Condition="'$(Configuration)' == 'Release'">--minify</TailwindMinify>
    <TailwindMinify Condition="'$(Configuration)' != 'Release'"></TailwindMinify>
  </PropertyGroup>

  <Target Name="BuildTailwindCSS" BeforeTargets="BeforeBuild" Condition="Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)')">
    <Message Importance="high" Text="Building Tailwind CSS..." />
    <Exec Command="&quot;$(TailwindExecutable)&quot; -i &quot;$(TailwindInputCss)&quot; -o &quot;$(TailwindOutputCss)&quot; $(TailwindMinify)" />
    <Message Importance="high" Text="Tailwind CSS built successfully!" />
  </Target>

  <Target Name="CleanTailwindCSS" AfterTargets="Clean" Condition="Exists('$(TailwindOutputCss)')">
    <Message Importance="high" Text="Cleaning Tailwind CSS output..." />
    <Delete Files="$(TailwindOutputCss)" />
  </Target>
</Project>

Step 5: Update project file

Add to your .csproj file:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <!-- ... existing content ... -->
  
  <Import Project="Build\ShellUI.targets" />
</Project>

Step 6: Build Tailwind CSS

# Build CSS manually
./tailwindcss -i wwwroot/input.css -o wwwroot/app.css

# Or build the project (MSBuild will handle it automatically)
dotnet build

Step 7: Add CSS to your layout

In your MainLayout.razor or App.razor:

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

Method 3: Play CDN (Prototyping Only)

The fastest way to try Tailwind — no build step, no install. Add one script to your HTML:

<head>
  <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
</head>

Pros: Instant setup, zero config.
Cons: Full Tailwind (~500KB+), no purging, not for production. Use for demos, prototypes, or Playground-style apps only.

For Blazor, add this to App.razor or your HTML host. Note: Design tokens (CSS variables) still need to be in your CSS for components to look correct.

Method 4: Using npm (Alternative)

If you prefer using npm and Node.js:

Step 1: Install Tailwind CSS

npm install -D tailwindcss
npx tailwindcss init

Step 2: Update tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './Components/**/*.{razor,html,cshtml}',
    './Pages/**/*.{razor,html,cshtml}',
    './wwwroot/**/*.html',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      // ... same theme configuration as above
    },
  },
  plugins: [],
}

Step 3: Create input.css

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

Note: This creates a minimal Tailwind setup. Add your custom CSS variables, colors, and design tokens as needed.

Step 4: Build CSS

npx tailwindcss -i wwwroot/input.css -o wwwroot/app.css

Verification

After setup, verify everything works:

Build the project:
```
dotnet build
```
Check for Tailwind CSS output:
- wwwroot/app.css should contain generated CSS
- Look for Tailwind utility classes in the output
Test in browser:
- Add some Tailwind classes to your components
- Verify they're styled correctly

Troubleshooting

Common Issues:

Tailwind CSS not building:
- Check that tailwind.config.js exists
- Verify content paths include your Razor files
- Ensure MSBuild targets are imported
Styles not applying:
- Check that app.css is linked in your layout
- Verify the CSS file is being generated
- Clear browser cache
Build errors:
- Ensure Tailwind CLI is executable
- Check file paths in configuration
- Verify MSBuild targets syntax

Getting Help:

Check the Tailwind CSS documentation
Review the ShellUI documentation
Open an issue on GitHub

Custom Themes & Fonts

🎨 Using Custom Themes from tweakcn

You can customize your theme similar to shadcn/ui. Copy theme configurations from tweakcn or similar tools and paste them into your wwwroot/input.css.

Example - Adding a custom theme:

Visit tweakcn
Customize colors, fonts, radius, etc.
Copy the generated CSS
Paste it into your wwwroot/input.css (replace the existing :root and .dark sections)

🔤 Installing Custom Fonts

To use custom fonts in your theme:

Method 1: Google Fonts (Recommended)

<!-- Add to your _Layout.cshtml or index.html -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Kode+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">

Then update your input.css:

:root {
  --font-sans: 'Kode Mono', ui-monospace, monospace;
  /* ... other variables ... */
}

Method 2: Local Font Files

/* Add to your input.css */
@import url('./fonts/kode-mono.css'); /* Your local font CSS */

:root {
  --font-sans: 'Kode Mono', ui-monospace, monospace;
  /* ... other variables ... */
}

Method 3: Font CDN

<!-- Add to your layout -->
<link href="https://cdn.jsdelivr.net/npm/@fontsource/kode-mono@5.0.0/index.css" rel="stylesheet">

📝 Font Fallbacks

Always include fallbacks in your font definitions:

:root {
  --font-sans: 'Custom Font', ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'Custom Mono', ui-monospace, 'SF Mono', monospace;
  --font-serif: 'Custom Serif', ui-serif, serif;
}

This ensures your design looks good even if the custom font fails to load.

🎯 Theme Examples

Dark Theme with Custom Colors:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
  /* ... customize all colors ... */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
  /* ... dark mode colors ... */
}

Custom Border Radius:

:root {
  --radius: 0.75rem; /* More rounded */
}

Custom Shadows:

:root {
  --shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
}

Next Steps

Once Tailwind CSS is set up:

Add ShellUI components (if using ShellUI) using dotnet shellui add
Customize the design system in input.css (use tweakcn for themes!)
Install custom fonts for the perfect look
Build your Blazor app with beautiful components
Deploy using your preferred hosting solution

Happy coding! 🚀

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Tailwind CSS Setup Guide for Blazor

Installation Methods Comparison

Prerequisites

Method 1: Using ShellUI CLI (Recommended)

Step 1: Install ShellUI CLI

Step 2: Initialize in your project

Step 3: Add components (optional)

Method 2: Manual Setup (Alternative)

Step 1: Download Tailwind CSS CLI

Step 2: Create CSS files

Step 3: Create Tailwind configuration

Step 4: Set up MSBuild integration

Step 5: Update project file

Step 6: Build Tailwind CSS

Step 7: Add CSS to your layout

Method 3: Play CDN (Prototyping Only)

Method 4: Using npm (Alternative)

Step 1: Install Tailwind CSS

Step 2: Update tailwind.config.js

Step 3: Create input.css

Step 4: Build CSS

Verification

Troubleshooting

Common Issues:

Getting Help:

Custom Themes & Fonts

🎨 Using Custom Themes from tweakcn

🔤 Installing Custom Fonts

Method 1: Google Fonts (Recommended)

Method 2: Local Font Files

Method 3: Font CDN

📝 Font Fallbacks

🎯 Theme Examples

Next Steps

Uh oh!

FilesExpand file tree

tailwind-setup.md

Latest commit

History

tailwind-setup.md

File metadata and controls

Tailwind CSS Setup Guide for Blazor

Installation Methods Comparison

Prerequisites

Method 1: Using ShellUI CLI (Recommended)

Step 1: Install ShellUI CLI

Step 2: Initialize in your project

Step 3: Add components (optional)

Method 2: Manual Setup (Alternative)

Step 1: Download Tailwind CSS CLI

Step 2: Create CSS files

Step 3: Create Tailwind configuration

Step 4: Set up MSBuild integration

Step 5: Update project file

Step 6: Build Tailwind CSS

Step 7: Add CSS to your layout

Method 3: Play CDN (Prototyping Only)

Method 4: Using npm (Alternative)

Step 1: Install Tailwind CSS

Step 2: Update tailwind.config.js

Step 3: Create input.css

Step 4: Build CSS

Verification

Troubleshooting

Common Issues:

Getting Help:

Custom Themes & Fonts

🎨 Using Custom Themes from tweakcn

🔤 Installing Custom Fonts

Method 1: Google Fonts (Recommended)

Method 2: Local Font Files

Method 3: Font CDN

📝 Font Fallbacks

🎯 Theme Examples

Next Steps