Debugging my upgrade to TailwindCSS's V2

So, I finally pulled the plug and updated TailwindCSS to V2 on my GatsbyJS blog. Below I outline the steps I took and the problems I encountered along the way (along with the solutions).


The first step was to install the latest TailwindCSS along with the necessary dependencies to run it.

npm install tailwindcss@latest postcss@latest autoprefixer@latest

I was following the excellent TailwindCSS install guide. The guide emphasized that you should be sure to remove future/experimental config options found within the tailwind.config.js file, which I did.

There are other use cases that may be relevant to your particular build so be sure to read through the install guide and make sure everything is hunky-dory. In my particular case I was able to proceed without making any further changes.

While I was doing some “house cleaning” I decided to tackle updating my GatsbyJS dependencies at the same time. Following the documentation first I ran

npm outdated

This displayed in iTerm2 all of the outdated packages along with the wanted version (minimum viable/preferred version) as well as the latest version. This is a good time to double-check that any updates you are about to make will not break your app. If everything is in the clear then run

npm update

This bumped my packages to the latest wanted version displayed when I ran npm outdated.

Once the updates are installed now would be a good time to run

gatsby clean

Followed by

npm start

I made sure to lock auto publishing with Netlify while I sorted out the upgrade as there are several breaking changes with TailwindCSS v2. It was a good thing I did because after running npm start I got this error:

PostCSS plugin tailwindcss requires PostCSS 8.
Migration guide for end-users:
https://github.com/postcss/postcss/wiki/PostCSS-8-for-end-users

After a bit of research, I came across this StackOverflow article, which linked to this that explained that

As of v2.0, Tailwind CSS depends on PostCSS 8. Because PostCSS 8 is only a few months old, many other tools in the ecosystem haven't updated yet, which means you might see an error like this in your terminal after installing Tailwind and trying to compile your CSS.

It went on to recommend running the following

npm uninstall tailwindcss postcss autoprefixer

then

npm install tailwindcss@npm:@tailwindcss/postcss7-compat @tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

After the new packages were installed I ran

gatsby clean

Maybe this is not necessary but it does not hurt to be thorough right? Next I ran

npm start

Now, I was able to spin up a localhost server on port 8000.

After making sure everything was happily running in the development environment I reenabled auto-publishing and pushed it to GitHub .

Off the bat, I noticed several changes. See if you can spot the differences...

Tailwind v1.png TailwindCSS v1

Tailwind v2.png TailwindCSS v2

Comments (1)

Isaac Tait's photo

For those using iTerm2 I highly recommend this tutorial to setup with ZSH and a really cool theme.

p.s. - I have no affiliation with the tutorial link above, I just found it very helpful and I am sharing it.