practical-asp-net / blazortailwindtemplate

Blazor Tailwind Project Template for dotnet new

View on Nuget.org.

Install template via nuget

From anywhere on your machine you can use this command to install the template directly from Nuget.

dotnet new --install PracticalDotNet.TailwindStarterProject::6.0-x

(where x is a specific version, check versions on nuget.org).

Install template from source

Alternatively, if you'd prefer, you can install it yourself from the source.

Download the source then change into the content folder.

There's more than one template in here, so pick the one you want and CD into that folder.

From there you can install the template using dotnet new --install.

There's no need to build anything first. In fact, if you do build the project inside the content folder you might end up with extra folders (like bin, obj) being included in the template.

cd content
dotnet new --install .

In this example we instruct dotnet to look in the current folder (.) for any templates and install any it finds.

It should find the .template.config folder which instructs it that this is a template for it to install.

Spin up a new project using the template

Once you have the templates installed you should find them in the list of templates for dotnet new.

dotnet new -l

Here's how it should appear in the list…

Blazor WASM Tailwind Project Template         blazorwasmtw      [C#]
Blazor WASM Tailwind Project Template         blazorservertw      [C#]

From here you're now free to use the template to create your very own Blazor + Tailwind project!

dotnet new blazorservertw - o ExampleApp
cd ExampleApp
dotnet watch

The above example creates a Tailwind CSS enabled Blazor Server project in an ExampleApp folder, then launches it using dotnet watch.

JIT Mode doesn't work automatically for Blazor WASM

Tailwind (from V3 onwards) now uses JIT mode by default, whereby you can launch the Tailwind CLI in watch mode then, as you make changes to your markup and stylesheets, Tailwind automatically rebuilds its stylesheet.

If you create a new Blazor Server project you'll find this works automatically. This is thanks to a small library called Tailwind.Extensions.AspNetCore which you can read more about here.

It launches the Tailwind CLI in watch mode when you launch your Blazor project.

Please note this doesn't work for the Blazor WASM project (because it runs in the browser, so we have no easy way to launch Tailwind as we can on the server).

The workaround is to launch it yourself, which you can do using this command (from the root folder for your project).

npm run buildcss:watch

Upgrading/downgrading the .NET version

When you create a new project using this template you'll discover that your new project references a specific version of .NET.

Taking the above example, if you looked at ExampleApp\ExampleApp.csproj you should see something like this...

<PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

<ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="6.0.0"/>
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="6.0.0" PrivateAssets="all"/>
</ItemGroup>

...

If you wish to use a different version of .NET you will need to change the TargetFramework and Package References. There are a couple of ways to change the referenced package versions:

• Manually change the version numbers in the .csproj
• Use the Nuget package manager in your IDE to downgrade the NuGet packages

You can also change the TargetFramework by manually updating the csproj or using your IDE to target a different version (for example net5.0).

blazortailwindtemplate's Issues

Only (re)build the Tailwind css file when needed

At the moment we're invoking the Tailwind CLI on every Debug build.

This is largely pointless because the first build creates wwwroot\css\app.css and thereafter there are only a few scenarios where we'd want to rebuild that file.

• When the version of Tailwind changes
• When we elect to run a Release build
• If we make changes to Styles\app.css

For any other Debug/Dev builds we're just doing unnecessary work (and slowing down the build).

Fixup CI workflows

Fixup CI workflows a bit to optimize:

• Move PR build out of main workflow that is publishing to NuGet each CI
• Add env flags to remove unnecessary spew for CI
• Ignore changes to .git files

Install the Tailwind CLI locally?

It may be preferable (at least as an option) to install the Tailwind CLI locally in the project's node_modules folder.

My understanding is that NPX would then always use that locally installed version.

This might help usage of the template in offline scenarios as, following the initial build (which would download and install the Tailwind CLI) there should be no need for subsequent builds to require an Internet connection.

Use the new Just-In-Time mode to react to css changes

The latest version of Tailwind ships with a brand new Just-In-Time mode.

https://tailwindcss.com/docs/just-in-time-mode

In theory this would remove the need to compile the Tailwind css file on every build but it's not yet clear (to me at least) how it works and how (or indeed if) it could be used with dotnet.

Support Blazor Server

The template is currently only available for Blazor WASM, would be useful to be able to create Blazor Server projects too.

Include README in package

Leverage the PackageReadmeFile to include the README in the package, which then provides a better experience on nuget.org and within other NuGet clients.

Support previous version(s) of .NET

The template currently allows for creating .NET 6 projects, would be great to be able to target .NET 5 and potentially earlier versions of .NET (Core) too.