Installation

Installing Tailwind as a PostCSS plugin

For most real-world projects, we recommend installing Tailwind as a PostCSS plugin. Most modern frameworks use PostCSS under the hood already, and there's a good chance you've used or are currently using other PostCSS plugins like autoprefixer.

If you've never heard of PostCSS or are wondering how it's different from tools like Sass, read our guide on using PostCSS as your preprocessor for an introduction.

If this is a bit over your head and you'd like to try Tailwind without configuring PostCSS, read our instructions on using Tailwind without PostCSS instead.

Install Tailwind via npm

For most projects (and to take advantage of Tailwind's customization features), you'll want to install Tailwind and its peer-dependencies via npm.

npm install tailwindcss postcss autoprefixer

Since Tailwind does not automatically add vendor prefixes to the CSS it generates, we recommend installing autoprefixer to handle this for you.

If you're integrating Tailwind with a tool that relies on an older version of PostCSS, you may see an error like this:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

In this case, you should install the PostCSS 7 compatibility build instead.

Add Tailwind as a PostCSS plugin

Add tailwindcss and autoprefixer to your PostCSS configuration. Most of the time this is a postcss.config.js file at the root of your project, but it could also be a .postcssrc file, or postcss key in your package.json file.

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

If you aren't sure where PostCSS plugins are configured for the tools you're using, you'll want to refer to the documentation for those tools to learn where this should go. A search for "configure postcss {my tool}" will get you the answer pretty fast too.

If you're using any other PostCSS plugins, you should read our documentation on using PostCSS as your preprocessor for more details about the best way to order them with Tailwind.

Create your configuration file

If you'd like to customize your Tailwind installation, generate a config file for your project using the Tailwind CLI utility included when you install the tailwindcss npm package:

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of your project:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

Learn more about configuring Tailwind in the configuration documentation.

Include Tailwind in your CSS

Create a CSS file if you don't already have one, and use the @tailwind directive to inject Tailwind's base, components, and utilities styles:

/* ./your-css-folder/styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind will swap these directives out at build-time with all of the styles it generates based on your configured design system.

If you're using postcss-import (or a tool that uses it under the hood, such as Webpacker for Rails), use our imports instead of the @tailwind directive to avoid issues when importing any of your own additional files:

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

If you're working in a JavaScript framework like React or Vue that supports directly importing CSS files into your JS, you can also skip creating a CSS file altogether and import tailwindcss/tailwind.css instead which has all of these directives already in place:

// app.js
import "tailwindcss/tailwind.css"

Building your CSS

How you actually build your project will depend on the tools that you're using. Your framework may include a command like npm run dev to start a development server that compiles your CSS in the background, you may be running webpack yourself, or maybe you're using postcss-cli and running a command like postcss styles.css -o compiled.css.

If you're already familiar with PostCSS you probably know what you need to do, if not refer to the documentation for the tool you are using.

When building for production, be sure to read our separate guide on optimizing for production to learn about tree-shaking unused styles for best performance.

If you're integrating Tailwind with a tool that relies on an older version of PostCSS, you may see an error like this when trying to build your CSS:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

In this case, you should switch to our PostCSS 7 compatibility build instead.

Using Tailwind without PostCSS

For simple projects or just giving Tailwind a spin, you can use the Tailwind CLI tool to generate your CSS without configuring PostCSS or even installing Tailwind as a dependency if you don't want to.

Use npx which is a tool that is automatically installed alongside npm to generate a fully compiled Tailwind CSS file:

npx tailwindcss-cli@latest build -o tailwind.css

This will create a file called tailwind.css generated based on Tailwind's default configuration, and automatically add any necessary vendor prefixes using autoprefixer.

Now you can pull this file into your HTML just like any other stylesheet:

<!doctype html>
<html>
<head>
  <!-- ... -->
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/tailwind.css" rel="stylesheet">
</head>
<body>
  <!-- ... -->
</body>
</html>

Using a custom CSS file

If you'd like to process any custom CSS alongside the default styles Tailwind generates, create a CSS file wherever you normally would and use the @tailwind directive to including Tailwind's base, components, and utilities styles:

/* ./src/tailwind.css */
@tailwind base;
@tailwind components;

.btn {
  @apply px-4 py-2 bg-blue-600 text-white rounded;
}

@tailwind utilities;

Then include the path to that file when building your CSS with npx tailwindcss build:

npx tailwindcss-cli@latest build ./src/tailwind.css -o ./dist/tailwind.css

Read about adding base styles, extracting components, and adding new utilities to learn more about adding custom CSS on top of Tailwind.

Customizing your configuration

If you'd like to customize what Tailwind generates, create a tailwind.config.js file using the Tailwind CLI tool:

npx tailwindcss-cli@latest init

This will create a minimal tailwind.config.js file at the root of your project:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

This file will automatically be read when building your CSS with npx tailwindcss build:

npx tailwindcss-cli@latest build ./src/tailwind.css -o ./dist/tailwind.css

If you'd like to keep your config file in a different location or give it a different name, pass the config file path using the -c option when building your CSS:

npx tailwindcss-cli@latest build ./src/tailwind.css -c ./.config/tailwind.config.js -o ./dist/tailwind.css

Learn more about configuring Tailwind in the configuration documentation.

Building for production

When building for production, set NODE_ENV=production on the command line when building your CSS:

NODE_ENV=production npx tailwindcss-cli@latest build ./src/tailwind.css -o ./dist/tailwind.css

This will make sure Tailwind removes any unused CSS and minifies the CSS file for best performance. Read our separate guide on optimizing for production to learn more.

Using Tailwind via CDN

Before using the CDN build, please note that many of the features that make Tailwind CSS great are not available without incorporating Tailwind into your build process.

To get the most out of Tailwind, you really should install it as a PostCSS plugin.

To pull in Tailwind for quick demos or just giving the framework a spin, grab the latest default configuration build via CDN:

<link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

Note that while the CDN build is large (73.2kB compressed, 3020.7kB raw), it's not representative of the sizes you see when including Tailwind as part of your build process.

Sites that follow our best practices are almost always under 10kb compressed.

HTML starter template

For Tailwind's styles to work as expected, you'll want to use the HTML5 doctype and include the responsive viewport meta tag to properly handle responsive styles on all devices.

<!doctype html>
<html>
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/path/to/tailwind.css" rel="stylesheet">
  <!-- ... -->
</head>
<body>
  <!-- ... -->
</body>
</html>

Many front-end frameworks like Next.js, vue-cli and others do all this for you behind the scenes automatically, so depending on what you're building you might not need to set this up.

PostCSS 7 compatibility build

As of v2.0, Tailwind CSS depends on PostCSS 8. Because PostCSS 8 is only a few months old, many other tools in the ecosystem haven't updated yet, which means you might see an error like this in your terminal after installing Tailwind and trying to compile your CSS:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

To help bridge the gap until everyone has updated, we also publish a PostCSS 7 compatibility build under the compat channel on npm.

If you run into the error mentioned above, uninstall Tailwind and re-install using the compatibility build instead:

npm uninstall tailwindcss postcss autoprefixer
npm install tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

The compatibility build is identical to the main build in every way, so you aren't missing out on any features or anything like that.

Once the rest of your tools have added support for PostCSS 8, you can move off of the compatibility build by re-installing Tailwind and its peer-dependencies using the latest tag:

npm uninstall tailwindcss @tailwindcss/postcss7-compat
npm install tailwindcss@latest postcss@latest autoprefixer@latest