Notice December 2nd 2020

With the release of Tailwind 2.0 much of this article is overkill for newly started projects. However, many companies do stay behind on versions to ensure consistency.

If you are staying behind on versions before Tailwind 2.0. Carry on. Otherwise, I’ll be posting a new workflow covering React with Tailwind 2.0.

The Motive

Many can appreciate the problems TailwindCSS attempts to solve, providing low opinions on how to style your application. It comes with a cost of long line of class selectors that tends to overtake the template logic of your application.

Another DEV.to author @ryanlanciaux wrote an article which you can find here Tailwind with React. This started my mad labratory experiments. I was motivated to leverage the fantastic tools TailwindCSS offers.

A CSS library that I have utilized before, Tachyons, has a similar utility class strategy as Tailwind. I implemented an alternative Styled Component concept to manage the utility classes provided by Tachyons.

Combining Ryan's process with my strategy for Tachyons. The two methods arrive at an efficient TailwindCSS workflow. It is setup intensive. Worth the effort for maintaining a clean Tailwind style strategy that will scale nicely as your project grows.

Note: If you just want to dive into the project without having to build from scratch. Scroll to the bottom of the article and run the Create React App template command that will scaffold the entire project and dependencies discussed in this article.

We need a Create React App

First, we need a fresh Create React App install.

npx create-react-app my-new-app

cd my-new-app

Deleting the standard boilerplate from Create React App

The instructions coming next will help you create the following folder tree. Initially you'll want to delete the React boilerplate. logo.svg, index.css, App.css and remove their imports from index.js and App.js.

src
│       ├── App.jsx
│       ├── App.test.js
│       ├── AppStyles.styles.tw.js
│       ├── README.md
│       ├── index.css
│       ├── index.js
│       ├── serviceWorker.js
│       ├── setupTests.js
│       ├── tailwind.config.js
│       └── tailwind.css

We need to install the rest of the dependencies to put Tailwind together with Styled-Components.

npm i --save tailwindcss tailwind.macro@next styled-components babel-plugin-macros postcss-cli autoprefixer

Create tailwind.config.js

Once the packages have installed. We need to initialize tailwind.config.js. We can customize Tailwind properties specific to the needs of our projects. For this example, I have added some configuration to change Tailwinds default 'blue-gray' tint to a flatter grayscale.

npx tailwind init

// ./src/tailwind.config.js
module.exports = {
  theme: {
    fontFamily: {
      display: ["Helvetica", "sans-serif"],
      body: ["Helvetica-Neue", "sans-serif"]
    },
    extend: {
      colors: {
        gray: {
          "100": "#f5f5f5",
          "200": "#eeeeee",
          "300": "#e0e0e0",
          "400": "#bdbdbd",
          "500": "#9e9e9e",
          "600": "#757575",
          "700": "#616161",
          "800": "#424242",
          "900": "#212121"
        }
      }
    }
  },
  variants: {},
  plugins: []
};

Note: You need to move tailwind.config.js to the .src folder. Create React App has ModuleScopePlugin which prevents Tailwind Macro and Babel Macro Plugin from calling the tailwind.config.js from root folder. There are ways around this, It wasn't a critical or urgent enough issue to add these additional steps just to put the config file back into root.

All other build formats that do not include the ModuleScopePlugin can serve tailwind.config.js from root folder as usual.

Create Tailwind.css

Create the following file tailwind.css in .src directory adding the base Tailwind variables that call the utilities from Tailwinds package.

//./src/tailwind.css

@tailwind base;

@tailwind components;

@tailwind utilities;

Create babel-plugin-macros.config.js

We need to address the tailwind-macro package to utilize Tailwinds config file. This allows us to use the tw macro, (we will create this very soon) and allows Babel to read all of Tailwinds utilities.

Create babel-plugin-macros.config.js in your root and copy the following settings into the file.

//./babel-plugin-macros.config.js

module.exports = {
  tailwind: {
    plugins: ["macros"],
    config: "./src/tailwind.config.js",
    format: "auto"
  }
};

Create postcss.config.js

And... finally we need to direct PostCSS to use Tailwind and Autoprefixer during compile. We will leverage this setup in a moment in our package.json file.

Add this file to your root directory.
postcss.config.js and copy the following settings into the file.

//./postcss.config.js

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

Update your package.json

Home stretch. Add the following scripts to your package.json This will call PostCSS Cli to build and watch while you're developing as create-react-app module reloading updates live. It will also automatically generate index.css for you.

// package.json
 "scripts": {
    "build:css": "postcss src/tailwind.css -o src/index.css",
    "watch:css": "postcss src/tailwind.css -o src/index.css",
    "start": "npm run watch:css & react-scripts start",
    "build": "npm run build:css react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
  }

Phew! Still with me? Awesome.

Note: File naming conventions are a matter of personal preference. I use the .jsx and styles.tw.js extensions for better visual distinction in my editors. .jsx gets the React logo, the .styles.tw.js gets the standard JavaScript logo. It helps differentiate template from the styles. Feel free to name your files however you find most comfortable.

Create AppStyles.styles.tw.js

Let's create our styled component first in the .src directory: Let's just get things up and running making incremental changes to ensure each change works correctly.

// ./AppStyles.styles.tw.js

import styled from "styled-components";

export const AppStyles = styled.div.attrs({
  className: "w-full h-screen bg-gray-100 p-2"
})``;

Create App.jsx

We begin creating our template, copy the following code into App.jsx. You'll notice, styling is a little off at the moment if you're running the app. We'll fix that shortly. We only have part of Tailwind working currently.

// ./src/App.jsx

import React from "react";
import "./index.css";
import AppStyles from "./AppStyles.styles.tw";

const App = () => {
  return (
    <AppStyles>
      <h1>Greetings Earthling</h1>
      <p>
        Welcome to your Create-React-App / TailwindCSS / Styled Components
        template
      </p>
      <h2>Resources / Documentation</h2>
      <ul>
        <li>
          <a href="https://reactjs.org/docs/create-a-new-react-app.html">
            ReactJS
          </a>
        </li>
        <li>
          <a href="https://tailwindcss.com/">TailwindCSS</a>
        </li>
        <li>
          <a href="https://styled-components.com/">Styled Components</a>
        </li>
      </ul>
    </AppStyles>
  );
};

export default App;

Adding 'tw' macro to AppStyles.styles.tw.js

BAM! Things are working nicely so far. Great job! Now, let's add the additional magic to extend the powerful capabilities of using Tailwind isolated behind Styled Components. We'll add the tw variable and import the tailwind.macrolibrary from NPM.

Update your AppStyles.styles.tw.js file with the new code written below.

// ./src/AppStyles.styles.tw.js

import styled from "styled-components";
import tw from "tailwind.macro";

const AppStyles = styled.div.attrs({
  className: "w-full h-screen flex flex-col items-center justify-center"
})`
  & {
    h1 {
      ${tw`font-sans text-6xl font-hairline text-6xl text-teal-500`}
    }
    p {
      ${tw`text-gray-700 text-lg`}
    }
    h2 {
      ${tw`text-2xl font-hairline mt-5 text-teal-500`}
    }
    ul {
      ${tw`inline-flex`}
    }
    li {
      ${tw`mr-5`}
    }
    a {
      ${tw`text-blue-500 hover:text-gray-500 hover:underline`}
    }
  }
`;
export default AppStyles;

Reviewing what we have just added, this setup now allows you to nest your Tailwind classes like you would with Sass. You can run through the entire component template using, class selectors, id's and html tags. It will follow all items from the parent container, each child and / or siblings. Pretty awesome, Right?

If you have the app currently running in the background. You need to restart it in order for all of the config files to compile with Create React App.

On completion of all steps, your file tree should look as follows.

Your root directory:

./styled-tailwind
├── .gitignore
├── README.md
├── babel-plugin-macros.config.js
├── node_modules
├── package-lock.json
├── package.json
├── postcss.config.js
├── public
├── src
└── yarn.lock

Your .src folder

./src
├── App.jsx
├── App.test.js
├── AppStyles.styles.tw.js
├── index.css
├── index.js
├── serviceWorker.js
├── setupTests.js
├── tailwind.config.js
└── tailwind.css

Great Job & Final Thoughts

That was a lot of setup prep work. There are many options you have available for your design workflow at this point. You're not limited to just Tailwind CSS classes. In between the backticks, you can also write normal CSS as follows. It offers lot of design possibilities and excellent opportunities to experiment with complex animations using Tailwind styled objects.

const AppStyles = styled.div.attrs({
    className: "w-full h-screen flex flex-col items-center justify-center"
})`
    & {
      h1 {
        ${tw`font-sans text-6xl font-hairline text-6xl text-teal-500`}
        transform: scale(1);
        transition: all 0.3s ease-in-out;
     }
      h1:hover {
      transform: scale(2);
    }
}
`;

A Create-React-App template.

You don't have to do any of this again. I have created a template that can be used with Create React App. Everything we have installed in this article, will be pre-installed and ready for your next creative spark.

npx create-react-app my-new-app --template styled-tailwind

cd my-new-app

npm run start

Voila! Greetings Earthling!