Learn how to get Tailwind CSS up and running in your project.
Installing Tailwind CSS can be a slightly different process depending on what other frameworks/tools you're using, so we've put together a bunch of guides that cover popular setups.
Don't see your favorite tool in the list? We're always working on new guides, but in the mean time you can follow the instructions for installing Tailwind CSS as a PostCSS plugin instead to get set up in no time.
Tailwind CSS requires Node.js 12.13.0 or higher.
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.
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 -D tailwindcss@latest postcss@latest autoprefixer@latest
Since Tailwind does not automatically add vendor prefixes to the CSS it generates, we recommend installing autoprefixer to handle this for you like we've shown in the snippet above.
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 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.
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.
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"
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 configure the purge option to remove any unused classes for the smallest file size:
// tailwind.config.js
module.exports = {
+ purge: [
+ './src/**/*.html',
+ './src/**/*.js',
+ ],
darkMode: false, // or 'media' or 'class'
theme: {
extend: {},
},
variants: {},
plugins: [],
}
Read our separate guide on optimizing for production to learn more 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.
Tailwind CSS requires Node.js 12.13.0 or higher.
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>
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 include 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.
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.
By default, the Tailwind CLI tool will run your CSS through Autoprefixer to add any necessary vendor prefixes. If you already have Autoprefixer set up in your build pipeline somewhere further down the chain, you can disable it in the Tailwind CLI tool using the --no-autoprefixer flag to avoid running it twice:
npx tailwindcss-cli@latest build --no-autoprefixer -o tailwind.css
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 for best performance. Read our separate guide on optimizing for production to learn more.
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 ({stats.default.brotlified} compressed, {stats.default.minified} 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.
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.
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 -D 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
npm install -D tailwindcss@latest postcss@latest autoprefixer@latest