css.TailwindCSS
Syntax
Returns
Use the css.TailwindCSS
function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to:
- Scan your templates for Tailwind CSS utility class usage.
- Compile those utility classes into standard CSS.
- Generate an optimized CSS output file.
Use this function with Tailwind CSS v4.0 and later, which require a relatively modern browser to render correctly.
Setup
Step 1
Install the Tailwind CSS CLI v4.0 or later:
npm install --save-dev tailwindcss @tailwindcss/cli
The Tailwind CSS CLI is also available as a standalone executable. You must install it outside of your project directory and ensure its path is included in your system’s PATH
environment variable.
Step 2
Add this to your site configuration:
build:
buildStats:
enable: true
cachebusters:
- source: assets/notwatching/hugo_stats\.json
target: css
- source: (postcss|tailwind)\.config\.js
target: css
module:
mounts:
- source: assets
target: assets
- disableWatch: true
source: hugo_stats.json
target: assets/notwatching/hugo_stats.json
[build]
[build.buildStats]
enable = true
[[build.cachebusters]]
source = 'assets/notwatching/hugo_stats\.json'
target = 'css'
[[build.cachebusters]]
source = '(postcss|tailwind)\.config\.js'
target = 'css'
[module]
[[module.mounts]]
source = 'assets'
target = 'assets'
[[module.mounts]]
disableWatch = true
source = 'hugo_stats.json'
target = 'assets/notwatching/hugo_stats.json'
{
"build": {
"buildStats": {
"enable": true
},
"cachebusters": [
{
"source": "assets/notwatching/hugo_stats\\.json",
"target": "css"
},
{
"source": "(postcss|tailwind)\\.config\\.js",
"target": "css"
}
]
},
"module": {
"mounts": [
{
"source": "assets",
"target": "assets"
},
{
"disableWatch": true,
"source": "hugo_stats.json",
"target": "assets/notwatching/hugo_stats.json"
}
]
}
}
Step 3
Create a CSS entry file:
@import "tailwindcss";
@source "hugo_stats.json";
Tailwind CSS respects .gitignore
files. This means that if hugo_stats.json
is listed in your .gitignore
file, Tailwind CSS will ignore it. To make hugo_stats.json
available to Tailwind CSS you must explicitly source it as shown in the example above.
Step 4
Create a partial template to process the CSS with the Tailwind CSS CLI:
{{ with resources.Get "css/main.css" }}
{{ $opts := dict "minify" (not hugo.IsDevelopment) }}
{{ with . | css.TailwindCSS $opts }}
{{ if hugo.IsDevelopment }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ else }}
{{ with . | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
{{ end }}
{{ end }}
{{ end }}
Step 5
Call the partial template from your base template, deferring template execution until after all sites and output formats have been rendered:
<head>
...
{{ with (templates.Defer (dict "key" "global")) }}
{{ partial "css.html" . }}
{{ end }}
...
</head>
Options
- minify
- (
bool
) Whether to optimize and minify the output. Default isfalse
. - optimize
- (
bool
) Whether to optimize the output without minifying. Default isfalse
. - disableInlineImports
- New in v0.147.4
- (
bool
) Whether to disable inlining of@import
statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have@import
statements anywhere in the file. Default isfalse
. - skipInlineImportsNotFound
- (
bool
) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. It is important to note that the inline importer does not process URL-based imports or those with media queries, and these will remain unaltered even when this option is disabled. Default isfalse
.