gatsby
Jul 1 2019

Install Gatsby with Tailwind CSS and PurgeCSS from Scratch

These days, I start every project by installing Tailwind CSS. My GatbsyJS projects are no exception. In this post I explain how to install Gatsby, Tailwind CSS and PurgeCSS to shrink the size of the overall Tailwind CSS file.

First, let's install Gatsby (full Gatsby installation instructions) and cd into your new project.

gatsby new my-project
cd my-project

Next, we'll install Tailwind CSS, autoprefixer and the gatsby-plugin-postcss plugin.

npm install --save tailwindcss autoprefixer gatsby-plugin-postcss

Now, open up your gatsby-config.js file and add the postcss plugin and its subsequent options:

module.exports = {
  // ...
  plugins: [
    {
      resolve: `gatsby-plugin-postcss`,
      options: {
        postCssPlugins: [require("tailwindcss"), require("autoprefixer")]
      }
    },
    // ...
  ],
}

When you did the gatsby new my-project command, Gatsby created this file src/components/layout.css. Open up the layout.css file and REPLACE EVERYTHING in it with the following 3 lines:

@tailwind base;
@tailwind components;
@tailwind utilities;

Now Tailwind styles are being pulled into our site. To test this, open src/components/layout.js and replace this code:

      <div
        style={{
          margin: `0 auto`,
          maxWidth: 960,
          padding: `0px 1.0875rem 1.45rem`,
          paddingTop: 0,
        }}
      >

… with this:

<div className="container mx-auto">

And open src/components/header.js and replace this code:

const Header = ({ siteTitle }) => (
  <header
    style={{
      background: `rebeccapurple`,
      marginBottom: `1.45rem`,
    }}
  >
    <div
      style={{
        margin: `0 auto`,
        maxWidth: 960,
        padding: `1.45rem 1.0875rem`,
      }}
    >
      <h1 style={{ margin: 0 }}>
        <Link
          to="/"
          style={{
            color: `white`,
            textDecoration: `none`,
          }}
        >
          {siteTitle}
        </Link>
      </h1>
    </div>
  </header>
)

… with this:

const Header = ({ siteTitle }) => (
  <header className={`bg-purple-800 mb-4`}>
    <div className={`container mx-auto py-4`}>
      <h1>
        <Link to="/" className={`text-white`}>
          {siteTitle}
        </Link>
      </h1>
    </div>
  </header>
)

Now view your site in the browser and you should see your Gatsby site with Tailwind styles applied:

gatsby build && gatsby serve

But if you view your source and check out the .css file linked in the <head> you'll see that it's pretty large. Let's reduce that filesize using PurgeCSS.

First, install the Gatsby PurgeCSS plugin:

npm i gatsby-plugin-purgecss

Then we add the plugin to our gatsby-config.js file. BUT, it should be at the end of the list of plugins:

module.exports = {
  // ...
  plugins: [
    // ... ALL OTHER PLUGINS HERE ...
    {
      resolve: `gatsby-plugin-purgecss`,
      options: {
        printRejected: false,
        develop: false,
        tailwind: true,
      },
    }
  ],
}

Now when you run...

gatsby build && gatsby serve

… you'll see in the command line something like:

gatsby-plugin-purgecss:
 Previous CSS Size: 488.41 KB
 New CSS Size: 9.67 KB (-98.02%)
 Removed ~478.75 KB of CSS

That's what we want!

And if you look at your source and check out the .css file generated, it will be much smaller.

Lastly, if you are serving up content via Markdown and want to add styles to your markdown pages, you will need to use the @apply Tailwind directive to style the HTML in your markdown content.

You can add those stylings in your src/components/layout.css file like this (assuming you have a wrapping CSS class named markdown):

@tailwind base;
@tailwind components;
@tailwind utilities;

/* purgecss start ignore */

.markdown h2 {
  @apply mb-4 font-bold text-2xl;
}

.markdown p {
  @apply mb-4;
}

/* purgecss end ignore */

Notice the two purgecss comments in the CSS file. Those actually tell PurgeCSS to ignore the classes between those two sets of comments. Learn more about Whitelisting and PurgeCSS. This was a big trouble part for me attempting to style HTML elements generated by a markdown file. For some reason, PurgeCSS was removing some of my CSS. Adding the comments like above fixed that issue once and for all!

The first part of this article is a modified version of Mike Francis's very helpful blog post on Gatsby & Tailwind CSS.

UPDATE - 2019-07-15 Learn how to add a responsive navigational menu to your new Gatsby / Tailwind site!