Tailwind is a utility-first CSS framework for rapidly building custom user interfaces. This guide will show you how to get started with Gatsby and Tailwind CSS.
There are three ways you can use Tailwind with Gatsby:
- Standard: Use PostCSS to generate Tailwind classes, then you can apply those classes using
- CSS-in-JS: Integrate Tailwind classes into Styled Components.
- SCSS: Use gatsby-plugin-sass to support Tailwind classes in your SCSS files.
You have to install and configure Tailwind for all of these methods, so this guide will walk through that step first, then you can follow the instructions for PostCSS, CSS-in-JS or SCSS.
This guide assumes that you have a Gatsby project set up. If you need to set up a project, head to the Quick Start guide, then come back.
Note: A config file isn’t required for Tailwind 1.0.0+
To configure Tailwind, you’ll need to add a Tailwind configuration file. Luckily, Tailwind has a built-in script to do this. Just run the following command:
- Install the Gatsby PostCSS plugin gatsby-plugin-postcss.
- Include the plugin in your
- Configure PostCSS to use Tailwind
postcss.config.js in your project’s root folder with the following contents.
- Use the Tailwind Directives in your CSS
You can now use the
@tailwind directives to add Tailwind’s utilities, preflight, and components into your CSS. You can also use
@apply and all of Tailwind’s other directives and functions!
To learn more about how to use Tailwind in your CSS, visit the Tailwind Documentation
These steps assume you have a CSS-in-JS library already installed, and the examples are based on Emotion.
- Import the Tailwind base styles
- Enable the Gatsby emotion plugin
twin.macroto create your styled component
See the Twin + Gatsby + Emotion installation guide for more information.
- Install the Gatsby SCSS plugin gatsby-plugin-sass and
- To be able to use Tailwind classes in your SCSS files, add the
tailwindcsspackage into the
postCssPluginsparameter in your
Note: Optionally you can add a corresponding configuration file (by default it will be
If you are adding a custom configuration, you will need to load it after
Note: This approach is not needed if you chose CSS-in-JS above, as you can already nest styles and
@apply rules directly from your
In case you need to create custom classes for elements for nested selectors, or for overriding external packages, you can create your own CSS/SCSS files.
- Create a new file and import your Tailwind directives.
This will be your ‘master’ CSS file, which you will import all other CSS within.
Note: if using SCSS (or another supported language, rename files/folders appropriately).
- Import any custom CSS files or add any custom CSS you need (optional)
Tailwind will swap these directives out at build-time with all of the styles it generates based on your configured design system.
- Import this file into your
gatsby-browser.js add an import rule for your Tailwind directives and custom CSS to pull them into your site.
Now we’ve fully configured Tailwind CSS, we want to make sure that only the classes we need are delivered to the browser. By default, Tailwind is a very large library because it includes every combination of every class you might think of. Most of these you won’t need, so we use PurgeCSS to remove any unused classes.
Note: By default, PurgeCSS only runs on the build command as it is a relatively slow process. The development server will include all Tailwind classes, so it’s highly recommended you test on a build server before deploying.
From v1.4.0 onwards PurgeCSS is built into Tailwind CSS, but the approaches needed are very similar.
1.4.0 and above
In 1.4.0 you can purge your CSS directly from your Tailwind config. You need to provide an array of strings telling it which files to process.
Full documentation on this can now be found on the Tailwind site - Tailwind PurgeCSS documentation
It is recommended you install the latest version of Tailwind CSS to get all available features. If you need to use an older version, you can follow the instructions on the PurgeCSS website - Purge CSS manually in older Tailwind versions