Using with Preprocessors
- Using PostCSS as your preprocessor
- Using Sass, Less, or Stylus

Using with Preprocessors

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 or would like to integrate Tailwind with a preprocessor for one reason or another.

Using PostCSS as your preprocessor

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.

Build-time imports

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 postcss-import

Then add it as the very first plugin in your PostCSS configuration:

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('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 {
  @apply px-4 py-2 rounded font-semibold bg-gray-200 text-black;
}
/* 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 {
  @apply px-4 py-2 rounded font-semibold bg-gray-200 text-black;
}

/* components/card.css */
.card {
  @apply p-4 bg-white shadow rounded;
}

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";

Nesting

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: [
    require('postcss-import'),
    require('tailwindcss/nesting'),
    require('tailwindcss'),
    require('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 postcss-nesting

Then pass the plugin itself as an argument to tailwindcss/nesting in your PostCSS configuration:

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss/nesting')(require('postcss-nesting')),
    require('tailwindcss'),
    require('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: [
    require('postcss-import'),
    require('tailwindcss/nesting')(require('postcss-nesting')),
    require('tailwindcss'),
    require('postcss-preset-env')({
      features: { 'nesting-rules': false }
    }),
  ]
}

Variables

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;

Vendor prefixes

For automatically managing vendor prefixes in your CSS, you should use Autoprefixer.

To use it, install it via npm:

npm install autoprefixer

Then add it to the very end of your plugin list in your PostCSS configuration:

module.exports = {
  plugins: [
    require('tailwindcss'),
    require('autoprefixer'),
  ]
}

Using Sass, Less, or Stylus

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.

The exact instructions will be different depending on which build tool you are using, so see our installation documentation 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%);
}

For the most cohesive development experience, it’s recommended that you use PostCSS exclusively.

Aside from that, each preprocessor has its own quirk or two when used with Tailwind, which are outlined with workarounds below.

Sass

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};
}

Less

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;
  }
}

Stylus

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');
  }
}

←Editor Support Optimizing for Production→

Edit this page on GitHub