Installing Tailwind CSS on top of the Gatsby starter default

If you are interested in using Tailwind CSS and you have not yet started your Gatsby project, you could potentially save time using the Gatsby Starter Tailwind. This post will be more beneficial for people who already have a Gatsby project and want to add Tailwind CSS manually. I recently added TailWindCSS to my blog.

Table of contents

• What is Tailwind?
• Installing new dependencies
• Create a tailwind.config.js file
• Configure Gatsby to use Tailwind CSS
• Include the Tailwind CSS directives
• Testing the Tailwind CSS installation
• Purging unused CSS
• That's a Wrap!

What is Tailwind?

If you are reading this post and do not yet know what Tailwind CSS is then I suggest you visit the Tailwind CSS site to learn more. I assume you have arrived here via a google search and you are ready to dive right in.

Installing new dependencies

First, you will need to install two new dependencies into your Gatsby project.

Tailwind CSS - A utility-first CSS framework for rapidly building custom user interfaces.

Gatsby PostCSS plugin - Tailwind CSS requires the PostCSS plugin, as we are adding Tailwind CSS to a Gatsby project we will use a Gatsby plugin instead of the default PostCSS plugin. If you want to learn more about PostCSS please visit the Post CSS plugin repository.

Install both plugins:

npm install tailwindcss gatsby-plugin-postcss --save

Create a tailwind.config.js file

Next, we want to create a tailwind.config.js file. The file is optional, but we will need it to reduce the size of our CSS.

npx tailwindcss init

This above command will create a minimal tailwind.config.js file at the root of our Gatsby project:

// tailwind.config.js
module.exports = {
    theme: {},
    variants: {},
    plugins: [],
}

You can learn more about the configuration file on the Tailwind CSS site.

As per the installation guide we will add the following Tailwind CSS plugins because we are using PostCSS and they recommend us to do so.

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

Configure Gatsby to use Tailwind CSS

Next, we will include the PostCSS Gatsby plugin and configure it to use Tailwind CSS and tell it where our tailwind.config.js file is.

// gatsby-config.js
plugins: [
    ...
    {
        resolve: 'gatsby-plugin-postcss',
        options: {
            postCssPlugins: [require('tailwindcss')('./tailwind.config.js')],
        },
    },
],

Alternatively, you can create a postcss.config.js, but I prefer the pattern of having all of my Gatsby plugins in the gatsby-config.js file.

Include the Tailwind CSS directives

I am working with a new Gatsby build, so I was able to remove all of the content in the layout.css file and replace that with the Tailwind CSS import directives.

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

You can learn more about the Tailwind CSS Directives on their site.

Testing the Tailwind CSS installation

We have completed the steps to get Tailwind CSS up and running in our Gatsby project so now we can test if everything was successful. The quickest way to test your Gatsby project is to launch the project using gatsby develop then open up your browser debugger and add a Tailwind CSS class to a DOM element. If you see a visual change and the styles included, then you know the above steps have worked.

Below I have added three Tailwind CSS classes to a H1 DOM node.

<h1 class="bg-black rounded-lg p-6">...</h1>

Purging unused CSS

When we added the directives above, we included the entire Tailwind CSS framework, after building my site, I noticed that my Gatsby CSS was now a whopping 1.08MB.

The last step is to reduce the number of classes included to a minimum. We can modify the tailwind.config.js so that we only add the CSS classes that we are using in our Gatsby components and pages.

// tailwind.config.js
module.exports = {
  purge: ['./src/**/*.js'],
  ...
}

To test this step, you can comment the line above and run gatsby build and then investigate the size of the CSS file being generated by Gatsby.

While researching the topic of CSS purging, I found the following plugin gatsby-plugin-purgecss but noticed that the above method would do the same but with fewer plugins. I am happier with fewer plugins, so I uninstalled it. Depending on your build, you may prefer to use the additional plugin.

That's a Wrap!

The next step will be to remove your old CSS and start to build your new Tailwind CSS driven site. If you have not already done so, I would recommend reading the core concepts of Tailwind CSS before you start building.

If you found this tutorial to be helpful or for any feedback, leave a comment below.