Since Tailwind is a PostCSS plugin, there’s nothing stopping you from using it with Sass, Less, Stylus, or other preprocessors, just like you can with other PostCSS plugins like
Autoprefixer
.
It’s important to note that
you don’t need to use a preprocessor with Tailwind
? you typically write very little CSS on a Tailwind project anyway, so using a preprocessor just isn’t as beneficial as it would be in a project where you write a lot of custom CSS.
This guide only exists as a reference for people who need to integrate Tailwind with a preprocessor for reasons outside of their control, not because it is a recommended practice.
If you’re using Tailwind for a brand new project and don’t need to integrate it with any existing Sass/Less/Stylus stylesheets, you should highly consider relying on other PostCSS plugins to add the preprocessor features you use instead of using a separate preprocessor.
This has a few benefits:
- Your builds will be faster
. Since your CSS doesn’t have to be parsed and processed by multiple tools, your CSS will compile much quicker using only PostCSS.
- No quirks or workarounds.
Because Tailwind adds some new non-standard keywords to CSS (like
@tailwind
,
@apply
,
theme()
, etc.), you often have to write your CSS in annoying, unintuitive ways to get a preprocessor to give you the expected output. Working exclusively with PostCSS avoids this.
For a fairly comprehensive list of available PostCSS plugins see the
PostCSS GitHub repository
, but here are a few important ones we use on our own projects and can recommend.
One of the most useful features preprocessors offer is the ability to organize your CSS into multiple files and combine them at build time by processing
@import
statements in advance, instead of in the browser.
The canonical plugin for handling this with PostCSS is
postcss-import
.
To use it, install the plugin via npm:
npm
install
-D
postcss-import
Then add it as the very first plugin in your PostCSS configuration:
module
.
exports
=
{
plugins
:
{
'postcss-import'
:
{
}
,
tailwindcss
:
{
}
,
autoprefixer
:
{
}
,
}
}
One important thing to note about
postcss-import
is that it strictly adheres to the CSS spec and disallows
@import
statements anywhere except at the very top of a file.
Won’t work,
@import
statements must come first
.btn
{
padding
:
theme
(
'spacing.4'
)
theme
(
'spacing.2'
)
;
}
@import
"./components/card"
;
The easiest solution to this problem is to never mix regular CSS and imports in the same file. Instead, create one main entry-point file for your imports, and keep all of your actual CSS in separate files.
Use separate files for imports and actual CSS
@import
"./components/buttons.css"
;
@import
"./components/card.css"
;
.btn
{
padding
:
theme
(
'spacing.4'
)
theme
(
'spacing.2'
)
;
}
.card
{
padding
:
theme
(
'spacing.4'
)
;
}
The place you are most likely to run into this situation is in your main CSS file that includes your
@tailwind
declarations.
Won’t work,
@import
statements must come first
@tailwind
base
;
@import
"./custom-base-styles.css"
;
@tailwind
components
;
@import
"./custom-components.css"
;
@tailwind
utilities
;
@import
"./custom-utilities.css"
;
You can solve this by creating separate files for each
@tailwind
declaration, and then importing those files in your main stylesheet. To make this easy, we provide separate files for each
@tailwind
declaration out of the box that you can import directly from
node_modules
.
The
postcss-import
plugin is smart enough to look for files in the
node_modules
folder automatically, so you don’t need to provide the entire path ?
"tailwindcss/base"
for example is enough.
Import our provided CSS files
@import
"tailwindcss/base"
;
@import
"./custom-base-styles.css"
;
@import
"tailwindcss/components"
;
@import
"./custom-components.css"
;
@import
"tailwindcss/utilities"
;
@import
"./custom-utilities.css"
;
To add support for nested declarations, we recommend our bundled
tailwindcss/nesting
plugin, which is a PostCSS plugin that wraps
postcss-nested
or
postcss-nesting
and acts as a compatibility layer to make sure your nesting plugin of choice properly understands Tailwind’s custom syntax.
It’s included directly in the
tailwindcss
package itself, so to use it all you need to do is add it to your PostCSS configuration, somewhere before Tailwind:
module
.
exports
=
{
plugins
:
{
'postcss-import'
:
{
}
,
'tailwindcss/nesting'
:
{
}
,
tailwindcss
:
{
}
,
autoprefixer
:
{
}
,
}
}
By default, it uses the
postcss-nested
plugin under the hood, which uses a Sass-like syntax and is the plugin that powers nesting support in the
Tailwind CSS plugin API
.
If you’d rather use
postcss-nesting
(which is based on the standard
CSS Nesting
specification), first install the plugin:
npm
install
-D
postcss-nesting
Then pass the plugin itself as an argument to
tailwindcss/nesting
in your PostCSS configuration:
module
.
exports
=
{
plugins
:
{
'postcss-import'
:
{
}
,
'tailwindcss/nesting'
:
'postcss-nesting'
,
tailwindcss
:
{
}
,
autoprefixer
:
{
}
,
}
}
This can also be helpful if for whatever reason you need to use a very specific version of
postcss-nested
and want to override the version we bundle with
tailwindcss/nesting
itself.
Note that if you are using
postcss-preset-env
in your project, you should make sure to disable nesting and let
tailwindcss/nesting
handle it for you instead:
module
.
exports
=
{
plugins
:
{
'postcss-import'
:
{
}
,
'tailwindcss/nesting'
:
'postcss-nesting'
,
tailwindcss
:
{
}
,
'postcss-preset-env'
:
{
features
:
{
'nesting-rules'
:
false
}
,
}
,
}
}
These days CSS variables (officially known as custom properties) have really good
browser support
, so you don’t need a preprocessor to use variables at all.
:root
{
--theme-color
:
#52b3d0
;
}
.btn
{
background-color
:
var
(
--theme-color
)
;
}
We use CSS variables extensively within Tailwind itself, so if you can use Tailwind, you can use native CSS variables.
You may also find that most of the things you’ve used variables for in the past can be replaced with Tailwind’s
theme()
function, which gives you access to all of your design tokens from your
tailwind.config.js
file directly in your CSS:
.btn
{
background-color
:
theme
(
'colors.blue.500'
)
;
padding
:
theme
(
'spacing.2'
)
theme
(
'spacing.4'
)
;
}
Learn more about the
theme()
function in our
functions and directives documentation
.
For automatically managing vendor prefixes in your CSS, you should use
Autoprefixer
.
To use it, install it via npm:
npm
install
-D
autoprefixer
Then add it to the very end of your plugin list in your PostCSS configuration:
module
.
exports
=
{
plugins
:
{
tailwindcss
:
{
}
,
autoprefixer
:
{
}
,
}
}
For the best development experience, we highly recommend that you
use PostCSS exclusively
, and that you don’t use preprocessors like Sass or Less in your Tailwind projects.
To use Tailwind with a preprocessing tool like Sass, Less, or Stylus, you’ll need to add an additional build step to your project that lets you run your preprocessed CSS through PostCSS. If you’re using Autoprefixer in your project, you already have something like this set up.
See our documentation on
installing Tailwind as a PostCSS plugin
to learn more about integrating Tailwind into your existing build process.
The most important thing to understand about using Tailwind with a preprocessor is that
preprocessors like Sass, Less, and Stylus run separately, before Tailwind
. This means that you can’t feed output from Tailwind’s
theme()
function into a Sass color function for example, because the
theme()
function isn’t actually evaluated until your Sass has been compiled to CSS and fed into PostCSS.
Won’t work, Sass is processed first
.alert
{
background-color
:
darken
(
theme
(
'colors.red.500'
)
,
10
%
)
;
}
Aside from that, some preprocessors have quirks when used with Tailwind, which are outlined with workarounds below.
When using Tailwind with Sass, using
!important
with
@apply
requires you to use interpolation to compile properly.
Won’t work, Sass complains about !important
.alert
{
@apply
bg-red-500
!important
;
}
Use interpolation as a workaround
.alert
{
@apply
bg-red-500 #
{
!important
}
;
}
In addition to this, Sass has trouble with Tailwind’s
screen()
function unless wrapped in parentheses.
Won’t work, Sass will generate an error
@media
screen
(
md
)
{
.foo
{
color
:
blue
;
}
}
Wrap the screen() function in parentheses
@media
(
screen
(
md
)
)
{
.foo
{
color
:
blue
;
}
}
Technically this results in an extra set of parentheses around your media query, but it still works.
When using Tailwind with Stylus, you can’t use Tailwind’s
@apply
feature without wrapping the entire CSS rule in
@css
so that Stylus treats it as literal CSS.
Won’t work, Stylus complains about @apply
.card
{
@apply rounded-lg bg-white p-4
}
Use @css to avoid processing as Stylus
@css
{
.card
{
@apply rounded-lg bg-white p-4
}
}
This comes with a significant cost however, which is that
you cannot use any Stylus features inside a
@css
block
.
Another option is to use the
theme()
function instead of
@apply
, and write out the actual CSS properties in long form:
Use theme() instead of @apply
.card
{
border-radius
:
theme
(
'borderRadius.lg'
)
;
background-color
:
theme
(
'colors.white'
)
;
padding
:
theme
(
'spacing.4'
)
;
}
In addition to this, Stylus has trouble with Tailwind’s
screen()
function unless you use interpolation and wrap it in parentheses.
Won’t work, Stylus will generate an error
@media
screen
(
md
)
{
.foo
{
color
:
blue
;
}
}
Use interpolation and parentheses as a workaround
@media
(
{
'screen(md)'
}
)
{
.foo
{
color
:
blue
;
}
}
Technically this results in an extra set of parentheses around your media query, but it still works.