loading...

Using Tailwind with Gatsby JS

jakedohm_34 profile image Jake Dohm ・3 min read

I'm beginning to rebuild my personal website using Gatsby JS, and of course I want to use my favorite CSS framework, Tailwind CSS! I searched around for a guide on how to use Gatsby and Tailwind together, and couldn't find anything with a full solution, so I decided to write this article as The Definitive Guide™ for how to set up Tailwind with Gatsby 😄.

FYI: If you follow this guide, hot reloading will still work and you'll also get reloading when you change your Tailwind configuration file!

Step 1: Install gatsby-plugin-postcss

gatsby-plugin-postcss is a Gatsby plugin that allows you to use PostCSS features in CSS files that you import into pages/components. Tailwind is built on PostCSS, so this is a great starting point!

To install the plugin, use your favorite package manager.

# Using NPM
npm install --save gatsby-plugin-postcss

# Using Yarn
yarn add gatsby-plugin-postcss

Step 2: Configure Gatsby to Use the PostCSS Plugin

Now that we've installed a plugin, we need to configure Gatsby to use it!

Open up your gatsby-config.js, and add 'gatsby-plugin-postcss' to the plugins array.

// gatsby-config.js

module.exports = {
    siteMetadata: { ... },
    plugins: [
        'gatsby-plugin-postcss',
        // ...
    ]
}

Step 3: Add PostCSS Config File

Our PostCSS plugin is installed, and Gatsby is using it, so all that's left is to configure the PostCSS side of things! To configure PostCSS, create an empty postcss.config.js file in your project's root (the same folder as the gatsby-config.js file).

Step 4: Install Tailwind

Now before we configure PostCSS to use Tailwind, we need to install it.

# Using NPM
npm install tailwindcss --save-dev

# Using Yarn
yarn add tailwindcss --dev

Step 5: Generate Tailwind Config File

To configure Tailwind, we'll need to add a Tailwind configuration file. Luckily, Tailwind has a built-in script to do this. Just run the following command (again, in your project's root directory).

./node_modules/.bin/tailwind init

This will create a tailwind.js file containing Tailwind's default configuration.

Step 6: Configure PostCSS

Okay, we've installed and configured Tailwind, now back to our PostCSS config. We need to add Tailwind to PostCSS's list of plugins.

// postcss.config.js

const tailwind = require('tailwindcss')

module.exports = () => ({
    plugins: [tailwind('./tailwind.js')],
})

In the example above, you'll see we're passing in a file path. That is the path to our configuration file. So if you'd like to move or rename the Tailwind configuration file, just remember to change the file path in your postcss.config.js file.

Note: You can add any other PostCSS plugins that you'd like to use, like autoprefixer, before or after Tailwind in the array of plugins.

Step 7: Add CSS File With Tailwind Directives

Everything should be ready to go, all we need to do now is to actually use Tailwind within our CSS! First, create a global.css file. I put mine at src/css/global.css. Then, add the following Tailwind directives to your new file:

// global.css

@tailwind preflight;

@tailwind components;

@tailwind utilities;

For this step, I opted to create a new global.css file, but you could just as easily put the Tailwind directives in an existing CSS file.

Step 8: Import Our Tailwind CSS

The last thing we need to do is to import our new CSS file into a page or layout so that our Tailwind CSS is actually injected into our pages. In layout.js, or wherever you want your Tailwind CSS to appear, add the following import:

// layout.js

import '../css/global.css'

You're Finished!

That's it, you should have a fully functional Tailwind + Gatsby setup, with Tailwind configuration, and Hot Reloading!

If you run into any trouble along the way, let me know in the comments and I'll happily help out and/or revise this article with any corrections!


I work for an awesome company called Good Work. We are an expert team of web developers helping design teams at agencies, brands and startups build things for web and mobile.

If you're looking for someone to help out on Gatsby, Vue, Tailwind, or other projects, don't hesitate to reach out!

Posted on Jan 3 '19 by:

Discussion

markdown guide
 
 

Thanks so much for sharing these!

For anyone who comes across these, a few notes:

  • The starter by Taylor Bryant is the only one that follows the same approach that this article does.
  • The LekoArts starter combines Tailwind and Styled Components, and the starter by Jason Lengstorf combines Tailwind with Emotion. Both of these are awesome, but different from my approach 😄

Lastly, Taylor Bryant's starter also includes PurgeCSS which removes all of the unnecessary Tailwind classes from your bundle!

 

@tailwind preflight is not a valid at-rule in Tailwind v1.0, use @tailwind base instead.

✅ Correct One

@tailwind base;

@tailwind components;

@tailwind utilities;

 

Thanks for sharing this! I'll test out this setup with Tailwind 1.0 and update my article accordingly 👍

 

Cool tip, instead of running ./node_modules/.bin/tailwind init you can just run npx tailwind init.

 

Ooh, that's awesome! Thanks!

 

I'm a fan of Tailwind myself, glad to see another tutorial for setting it up! As a follow-up, have you considering looking into setting up PurgeCSS? It's a popular tool to pair with Tailwind, since it'll find and remove all classes you're not using from the stylesheet.

 

Hey Max!

A couple people have mentioned that, so I think I'll post another short article on how to set that up. In the meantime, this starter has Tailwind (via PostCSS) and PurgeCSS set up: github.com/taylorbryant/gatsby-sta...

 

Was just thinking about this today! Book marking for later!