Getting Started
A guide to using Tailwind with common CSS preprocessors like Sass, Less, and Stylus.
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 anyways 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:
@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:
// postcss.config.js
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
/* components.css */
.btn {
padding: theme('spacing.4') theme('spacing.2');
/* ... */
}
/* Will not work */
@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
/* components.css */
@import "./components/buttons.css";
@import "./components/card.css";
/* components/buttons.css */
.btn {
padding: theme('spacing.4') theme('spacing.2');
/* ... */
}
/* components/card.css */
.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 like @apply
and @screen
.
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:
// postcss.config.js
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 work-in-progress 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:
// postcss.config.js
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:
// postcss.config.js
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 recommended 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, each preprocessor has its own quirk or two 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};
}
When using Tailwind with Less, you cannot nest Tailwind’s @screen
directive.
Won't work, Less doesn't realise it's a media query
.card {
@apply rounded-none;
@screen sm {
@apply rounded-lg;
}
}
Instead, use a regular media query along with the theme()
function to reference your screen sizes, or simply don’t nest your @screen
directives.
Use a regular media query and theme()
.card {
@apply rounded-none;
@media (min-width: theme('screens.sm')) {
@apply rounded-lg;
}
}
Use the @screen directive at the top-level
.card {
@apply rounded-none;
}
@screen sm {
.card {
@apply rounded-lg;
}
}
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 doesn’t support nesting the @screen
directive (just like Less).
Won't work, Stylus doesn't realise it's a media query
.card {
border-radius: 0;
@screen sm {
border-radius: theme('borderRadius.lg');
}
}
Instead, use a regular media query along with the theme()
function to reference your screen sizes, or simply don’t nest your @screen
directives.
Use a regular media query and theme()
.card {
border-radius: 0;
@media (min-width: theme('screens.sm')) {
border-radius: theme('borderRadius.lg');
}
}
Use the @screen directive at the top-level
.card {
border-radius: 0;
}
@screen sm {
.card {
border-radius: theme('borderRadius.lg');
}
}