[Tutorial] Como integrar ASP.NET e Tailwindcss (E o melhor, sem o Node.js)

No embalo do lançamento do .Net 8.0 e da estabilização do Blazor United, Vim postar um pequeno tutorial de como adicionar o Tailwindcss em qualquer aplicação ASP.NET, seja ela: MVC, Razor Pages ou Blazor. E melhor, sem tocar no Node.js. Utilizando apenas o binário standalone da cli do Tailwind.

Vamos entender o plano

Primeiro vamos entender as ferramentas que vamos utilizar. Basicamente, iremos integrar a Cli Standalone do Tailwind ao MSBuild do .Net. Fazendo com que ele realize o download automático das dependências e rode o bundle do tailwind após cada build.

O que é a Cli do Tailwind e por que podemos utilizá-la sem o Node?

O Tailwind possui uma Cli em formato binário que já engloba um runtime javascript (sinceramente não sei qual). De forma que é uma aplicação que pode funcionar sozinha, independente de qual framework ou linguagem iremos utilizar.

O que é o MSBuild?

O MSBuild é a ferramenta de build padrão do framework .Net, Se ainda não sabia o que eram os arquivos .csproj na raiz de sua aplicação, bom agora sabe: é a configuração de build. Ela diz ao MSBuild qual compilador estamos utilizando e qual o framework target. Ele também é capaz de realizar tarefas customizadas pelo usuário em partes específicas do seu círclo de execução. O que vamos utilizar para fazer o download da Cli do Tailwind e executá-la em cada build.

Mãos na massa!

Vamos passo a passo construir essa integração. Eu criei um projeto Blazor do zero, partiremos dele, caso esteja utilizando outro template, basta adaptar algumas linhas de código que vou indicar durante o tutorial. Esta é a situação atual:

O básico

Qualquer projeto Tailwind precisa de um arquivo css input e sua configuração. Vamos utilizar a estrutura recomendada para novos projetos. Crie na raiz do projeto uma pasta chamada Assets É nela que vamos deixar todas as informações pre build. Nela crie os seguintes arquivos: Assets/tailwind.config.js e Assets/css/app.css (Lembre que no windows a barra é invertida). Agora temos a nova estrutura:

No arquivo Assets/css/app.css basta inserir as regras básicas do Tailwind (Ou as suas próprias):

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

No arquivo Assets/tailwind.config.js insira o seguinte:

/** @type {import('tailwindcss').Config} */
module.exports = {
	content: [
    	"Components/*.razor",
    	"Components/**/*.razor",
	],
	theme: {
  	extend: {},
	},
	plugins: [],
}

No array content é onde estão as regras de quais arquivos serão buscados para definir quais classes serão injetadas no arquivo de output. Adapte para seu framework específico, No caso de Razor pages por exemplo é necessário substituir a pasta Components por Pages, e no MVC além de ser necessário apontar para a pasta Views também é necessário incluir os arquivos cshtml.

Baixando a Cli automaticamente

Vamos criar todos os arquivos restantes para a integração. Crie uma pasta dentro de Assets chamada scripts, e dentro dela outra chamada tailwind. e crie os seguintes arquivos:

Os arquivos que terminam com .sh são scripts para Linux e Mac enquanto os .ps1 são arquivos Powershell para Windows. Para não alongar ainda mais o post irei apenas mostar os arquivos .sh, porém todos os arquivos utilizados nessa integração serão encotrados nesse Gist.

Adicione o seguinte código no arquivo bootstrap.sh (faça o mesmo para o ps1 como esse código):

#! /usr/bin/env bash

set -e # Exit on error

OS=""
case "$(uname -s)" in
	"Linux")  OS="linux";;
	"Darwin") OS="macos";;
esac

ARCH=""
case "$(uname -m)" in
	"x86_64")  ARCH="x64";;
	"amd64")   ARCH="x64";;
	"arm64")   ARCH="arm64";;
	"aarch64") ARCH="arm64";;
	"armv7l")  ARCH="armv7";;
esac

PACKAGE="tailwindcss-${OS}-${ARCH}"
OUTPUT="Assets/bin/${PACKAGE}"
DOWNLOAD_URL="https://github.com/tailwindlabs/tailwindcss/releases/latest/download/${PACKAGE}"

if [ ! -e "$OUTPUT" ]; then
	echo "Bootstraping Tailwindcss"

	mkdir -p "$(dirname ${OUTPUT})"
	curl -sL -o "${OUTPUT}" "${DOWNLOAD_URL}"
	chmod +x "${OUTPUT}"
fi

Se rodar este script a partir da raiz do projeto ele já vai baixar a cli do tailwind no local correto. Mas vamos automatizar este download no MSBuild.

Adicione o seguinte trecho de código no seu arquivo csproj:

<Target Name="TailwindRestore" BeforeTargets="Restore">
  <Exec
	Command="bash Assets/scripts/tailwind/bootstrap.sh"
	Condition=" '$(OS)' == 'Unix'"
  />
  <Exec
	Command="powershell -File Assets/scripts/tailwind/bootstrap.ps1"
	Condition=" '$(OS)' == 'Windows_NT'"
  />
</Target>

O trecho BeforeTargets="Restore" no Target garante que ele seja executado todas as vezes que o restore termina. Logo, quando realizar o comando dotnet restore ou dotnet build ele baixará a cli se não estiver disponível.

Realizando o build do Css

Se está acompanhando o passo a passo já deve ter adivinhado que os arquivos chamados run são os scripts necessários para rodar a cli e fazer o build do seu css.

Vamos adicionar o seguinte para o arquivo run.sh (adicione tambem este conteúdo no .ps1)

#! /usr/bin/env bash

set -e # Exit on error

OS=""
case "$(uname -s)" in
	"Linux")  OS="linux";;
	"Darwin") OS="macos";;
esac

ARCH=""
case "$(uname -m)" in
	"x86_64")  ARCH="x64";;
	"amd64")   ARCH="x64";;
	"arm64")   ARCH="arm64";;
	"aarch64") ARCH="arm64";;
	"armv7l")  ARCH="armv7";;
esac

PACKAGE="tailwindcss-${OS}-${ARCH}"
BIN="Assets/bin/${PACKAGE}"

CONFIG="Assets/tailwind.config.js"
INPUT="Assets/css/app.css"
OUTPUT="wwwroot/tailwind/tailwind.min.css"

echo "Running Tailwindcss build"

# Tailwindcli
$BIN -i "${INPUT}" -o "${OUTPUT}" -c "${CONFIG}" -m

Agora vamos adicionar um target para rodar estes scripts após cada build, basta adicionar o seguinte target no seu csproj:

<Target Name="TailwindRun" BeforeTargets="Build">
  <Exec
	Command="bash ./Assets/scripts/tailwind/run.sh"
	Condition=" '$(OS)' == 'Unix'"
  />
  <Exec
	Command="powershell -File ./Assets/scripts/tailwind/run.ps1"
	Condition=" '$(OS)' == 'Windows_NT'"
  />
</Target>

Vamos Rodar!

Estes scripts irão criar um arquivo chamado tailwind.min.css em uma pasta chamada Tailwind no wwwroot da sua aplicação. Para fazer com que as funções tenham efeito faça o link desse arquivo no início da sua aplicação, no meu caso: Components/app.razor.

Tudo Pronto. Basta um dotnet build e vamos ver a mágica acontecer! Se tudo deu certo você deve ver algo um output como esse:

Dicas e Avisos

Uma dica rápida é não esquecer de adicionar o tailwind.min.css no seu .gitignore, não creio que deseje ter que dar commit em cada mudança nesse arquivo já que ele vai ser gerado automaticamente a cada build.

Alguns avisos importantes são: Infelizmente não encontrei uma maneira de rodar o build do css a cada hot reload no modo watch do dotnet. Ainda é possível recompilar o css ao realizar um Full reload com Ctrl+r. Outro aviso é o fato de eu mesmo não ter testado os scripts no Windows. Então verifique se funcionam e relatem sua experiência, caso contrário.