Using Tailwind CSS with Zendesk’s new custom pages (but really it’s not about that at all and instead it’s a story of loss and redemption)

This article is part of a wider family of articles exploring Zendesk custom pages. You can find out more about other technologies we used and their implementations into custom pages in this article.

Ok, real talk, this is not going to be a typical “how-to” article. Instead this is going to be a “how-we-did-before-compatibility-issues-were-fixed-and-now-what-do-we-write-about?” With a subtitle of: Maybe build a basic cake before you build a 17 layer cake. Because on this project, we got really cute. Obviously React, but why not Tailwind? Has anyone worked with Typescript before? No, fine, let’s toss that in there also. Webpack? Psh, duh. This was basically us:

It was fine though! Learning new technologies is fun and if you’ve got a good reason for doing it, do it. The problem that quickly emerged was one that experience will hopefully drill into our heads: once you start throwing all of those ingredients into the mix, you are putting yourself at the mercy of the module compatibility gods. And the gods bit us. Then they unbit us, which is great for the person reading this today, but it makes writing an article about the experience really difficult. Tailwind 3 + CRA 5.0 + PostCSS 8? Ask January me. January me was crying because Tailwind needed CRA 4 and PostCSS 7, and for some reason that I can’t remember we also needed craco. npm kept telling me to get my life in order because peer dependencies. “Not recommended” became “how the hell else do I do it” with — legacy-peer-deps getting added to every npm install. I’m sure that we’ve all run into some version of this and we spend hours googling trying to find the right answer.

Somehow though, it all came together. Everything was running properly and at that point I was too scared to even look at my dependencies for fear that even seeing the “wrong” version would cause it to break. Project finishes up and then I take a month off from work. Now that I’m back, let’s get an article written about this. Going through my notes…my very well-organized and not at all scattered across Things, Drafts, and Notes notes, I realize that there are new compatibility issues and the article that I want to write needs to change. I banged my head against the wall trying to install previous compatibility-specific versions of tailwind and postcss and get them working with craco and let’s just say it was a rough couple of days. What did I do? I had an epiphany. Stay with me, dear reader, to learn the secrets of this momentous light-bulb moment.

The Great Epiphany

I gave up. The muscle memory of trying to force this compatibility install was so strong that until that moment, I didn’t even consider following the actual, current documentation for Tailwind using Create React App. Let me walk you through the documentation (with some minor typescript additions) in case you don’t like clicking links.

npx create-react-app project-name - template typescript
cd project-name
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

(Stop me if I’m going too fast)

In your project root, look for tailwind.config.js. In the content array add:

"./src/**/*.{js,jsx,ts,tsx}",

Now go to ./src/index.css and replace everything there with this:

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

Finally, the most difficult step:

npm run start

Oh hey look, it works. Which, back in January, was not what I said. What I did say was very likely a string of words that I’m not going to publish in an article where I’m pretending to be slightly professional, followed by some sort of failure in my terminal, and finally a google search for said failure, sending me down the rabbit hole that I both lived in for a month and forgot to move out of two months later.

What I learned

• First and foremost, if you intend to publish a tutorial or article or any other kind of content, write it while you’re doing the work.
• Write it in one place and in a way that when you read it again, you’re not deciphering hieroglyphics from an ancient civilization of you.
• Trust the documentation, even if it wasn’t right when you tried it a month ago. Turns out, things change and you could be wasting your time trying to do it the wrong way.
• If you’re going to add the hot new framework to your app, don’t add five other hot new things to your app.
• Because I can’t stress this enough, WRITE THE CONTENT WHILE YOU’RE DOING THE WORK.

I’m hoping that everyone reading this is like, “Yeah Greg, we know. That’s How To Dev Advocacy 101.” If this is just my tirade of ineptitude and stubborn commitment to doing things incorrectly, laid bare for the world, that means that y’all are probably on the right track to making great documentation.

But for those of you who have gone through similar headaches, I see you. You’re not alone. Together we can do better next time and instead of writing this article, we can talk about how much we love Tailwind because oh my god it really is the greatest thing in the world. Like seriously, go use it.