Pinegrow’s External Build Process for Tailwind CSS

In this video, I’m going to show you how we install the latest version of Tailwind and configure it to work with Pinegrow’s External Build Process.

Tailwind just released version 3.2 a few weeks ago, and I’ve had several people reach out to me asking how they can get it working with Pinegrow. Thankfully, Pinegrow comes with options to use either their built-in compiler, which they update every few months, or you can use an external build process for any Tailwind version you want.

Intro

I’m Adam Lowe, President of Peak Performance Digital. If you find content like this helpful, I’d love it if you can give me a thumbs up and hit that subscribe button. It may not seem like much, but it means a lot to me.

Special Thanks

I want to give a big shout-out to Dom Sinclair, who helped light a fire under me to finally create this video after months of procrastination. He and I worked together over email to take the official Tailwind documentation, the Pinegrow documentation, and some miscellaneous notes that I’ve collected over time to compile a very nice walkthrough of this process on his GitHub Page, which I’ll link below. He’s also working on other documentation, which might be interesting, so keep an eye on his page.

The process I describe here differs just a tiny bit from his, but it’s effectively the same. If you want to copy and paste the commands and code from this video, just head on over to my blog, which is linked below. There, I’ll have a full transcript of this video along with commands that you can copy and paste.

Documentation Differences

Tailwind’s documentation is great and easy to follow, but it doesn’t account for the way Pinegrow works, so we had to make some modifications. Similarly, Pinegrow’s documentation is also good, but it was written for version 2.x and has footnotes on how to make it work with version 3. This makes sense because Pinegrow continues to support both versions, but it makes the documentation a bit hard to follow, especially for people who are new to either Pinegrow or to Tailwind.

What You’ll Need

For this video, I’ll be using the Pinegrow Desktop application with the Tailwind add-on enabled. This process won’t work with the Pinegrow WordPress Plugin Beta, and I doubt it will work with the release version anytime in the foreseeable future. I suppose we can add this to the list of benefits that the Desktop Pinegrow product has over the upcoming plugin.

What is the Tailwind Compiler?

So, what is this external compiler, and why would we want to use it anyway? Well, starting in version 3, Tailwind requires a Just in Time compiler that looks at the classes you are using and compiles a tailwind.css file that includes only the classes you are using. This compiler has tremendous benefits, but it does add an extra layer of complexity.

Why Use the External Build Process?

How does all this fit in with Pinegrow, you might be asking? Well, Pinegrow comes with a built-in Tailwind compiler, but it’s not always the latest version, and it only has limited configuration options. If you want to run bleeding edge versions of Tailwind, or if you want to add Tailwind plugins and modify your configuration, then you’ll probably want to consider bypassing the internal compiler and using their external build process.

Benefits of the Internal Compiler

Before you head down this road, however, it’s important to realize that the built-in compiler has some pretty significant benefits. First, it’s by far the easiest and most hassle-free to use Tailwind. You don’t need to worry about things like installing Node.js on your machine or keeping a compiler running while you are working. Pinegrow’s visual controls and WordPress editor stylesheet also work without any additional configuration. The biggest reason, at least for me, for using the built-in compiler is compatibility with the upcoming Pinegrow WordPress Plug-in. Since the external build process won’t work with the plugin, using the built-in compiler lets me move projects back and forth without any hassles.

Options for WordPress Plugin Users

Before you ask, yes, I am familiar with the Winden Tailwind plugin from dPlugins, and I have a license. I have gotten it to work with the Pinegrow plugin, and It’s actually quite a nice plugin. It adds extra dependencies to your project, and there are some considerations if you want to use Pinegrow’s visual Tailwind tools with the Winden compiler, but it does work. Maybe I’ll do a follow-up video demonstrating it someday.

Tailwind and WordPress

There is one other thing I want to mention before we get into the walkthrough, and that is how Tailwind works in conjunction with WordPress or with other frameworks. To put it bluntly, they don’t play nicely together.

New Tailwind users are always surprised to find that pretty much every style gets reset by Tailwind. This is very helpful when you want to have full control over the layout of every component and piece of content on your site. Still, it’s a bit disconcerting when you open the WordPress block editor or a post and see that all your headings, lists, quotes, and everything else look like regular unstyled text.

There are definitely some techniques and strategies to use when you are working with Tailwind and WordPress, such as creating editor stylesheets and re-defining styles. Those things are beyond the scope of this video, though, so I’ll have to save them for another time.

For this video, I’m going to start inside Pinegrow so you can see how it works with Tailwind. In practice, the order doesn’t matter. You can do it this way, or you can configure Tailwind first.

Demonstration

Now, let’s get on to the demonstration.

I’ll start by opening Pinegrow and creating a new Tailwind version 3 page. If you look at this list, you’ll actually see support for Tailwind version 2.x and 3.x. At the time of this video, using Pinegrow 6.8, Pinegrow is using Tailwind versions 2.2.6 and 3.0.12. Once I have my index.html created, I’ll save that page and open the directory I saved it to as a project.

Let’s drag a heading 1 element onto the page and give it a few Tailwind classes so we can make sure everything is working as expected. Here, I’ve added the font-bold, text-3xl, text-indigo-500, and underline classes. You can see how they immediately take effect in the preview window.

font-bold, text-3xl, text-indigo-500, underline

When you open the code panel, you’ll see that Pinegrow is actually using the Tailwind CDN at this point. In fact, I’ll switch over to VS Code for a minute so we can look at what’s going on in the Project directory.

A First Look at Pinegrow’s File Structure

In the project root directory is that index.html file we just created. You’ll also see a pingrow.json file, which is where Pinegrow stores project information. In the _pginfo directory, we have the fonts.json file, which just stores font definitions for some common Google fonts. Since we are using the Tailwind CDN at this point, nothing else is needed. The browser calls the Tailwind CSS CDN to render any classes we put on the page.

Activate the Design Panel

Now, we’ll activate the design panel. This is where things get interesting. Right away, you see the pre-defined colors and variations. This design panel also gives us the ability to edit these colors or to add new ones. We can also select the default sans serif and serif fonts that we want to use for our project and whether we want any headings to default to one of those styles. The design panel also lets us set the page’s background color or background image. For now, I’m just going to set my default sans serif font to “Arial” and my serif font to “Georgia.”

There are a few more things that the design panel can do, but these are the important points for today.

Files Created by Pinegrow’s Tailwind Design Panel

When I reload the project, you’ll see that Pinegrow has created a few more files. In the root, we have the projectdb.pgml file. This file stores the design panel settings. It also created a new file inside the _pginfo directory, class.tracker.json. This is a pretty cool file that tracks which Tailwind classes are used in the project so that the compiler can include them in the tailwind.css file.

Speaking of which, that tailwind.css file is now no longer being pulled from the CDN. It’s now being created by the built-in compiler and stored in the tailwind_theme directory, as you can see here. And, of course, our index.html file has been updated automatically to point to the new tailwind.css file.

I’ll come back to the design panel for just a minute, so you can see the compiler options. Here, you can see that we have options for Tailwind versions 2 and 3, the non-JIT compiler for version 2, and the external build process.

For now, let’s leave this as-is and cancel the dialog box.

Activating the Pinegrow WordPress Module

The next big change inside Pinegrow comes when we activate the WordPress module. If you don’t plan to use Tailwind with WordPress, this may not be important to you, but it’s still worth knowing.

To activate the WordPress module, I’ll go to the root of my index.html file, open the “WordPress Theme Builder” panel, and select “Activate WordPress.” I’ll fill in this information for my test theme and click the “Save settings” button.

Pinegrow Variables

In case you are wondering, I’m using variables for my theme folder and site URL. This is a cool feature that lets me set those variables in my local client’s settings and use them in the project so I can share this project across multiple computers or developers without needing to change the theme settings each time.

I’ll save the page and export the theme so that we don’t have to see dialogs about it again.

Files Created by Pinegrow’s WordPress Module

Now, let’s come back to the project folder and see what’s changed. Obviously, Pinegrow has added a functions.php and a style.css file since those are required for WordPress themes. Inside our tailwind_theme folder, it’s also created a tailwind_for_wp_editor.css file. This is an important file that’s worth discussing for a minute.

WordPress Block Editor Stylesheet

It’s important to understand that WordPress’ Block Editor doesn’t generally pick up the theme’s styles. Since we’re using Tailwind to style our theme, this means that the Block Editor will not look anything like what we see on the front-end of the website. This new CSS file tried to remedy that by creating a special version of the tailwind.css file that is designed specifically for the Block Editor.

It’s also important to note that this file has some specific logic and is only generated by the internal Tailwind compiler. It’s not something that can be easily generated by the external build process. I point this out because you’ll probably want to temporarily switch to the internal compiler, then back to the external build process again from time to time to update this file as you use different classes.

Creating Additional Directories

Pinegrow has also created an “inc” folder with custom.php, which is a great place for you to put any custom WordPress functions that you don’t want to be overwritten by Pinegrow.

While we are here, let’s create a few other directories that will be helpful in our project. According to the WordPress theme handbook, they suggest creating a folder called assets with “CSS”, “images,” and “js” subfolders inside it to hold those types of files. I like to stick to this structure whenever possible, so I’ll create them now.

mkdir assets
mkdir assets/css
mkdir assets/js
mkdir assets/images

Now, we’ll leave Pinegrow for a bit while we configure our Tailwind compiler. For this, I’ll do most of the work inside VS Code.

Tailwind Prerequisites

For these next steps, you’ll need three things. One, you need to have node.js installed. If you don’t have that, just go to https://nodejs.org/, download it, and install it. You’ll also need some sort of text editor. I use VS Code, but any editor will be fine. And lastly, you’ll need your terminal. Since VS Code has one built-in, I’ll use it for this demo.

Install and Configure Tailwind

The first thing we’ll do here is to create a Node.js project and initialize it. Running `npm init -y` will do that for you and will create a default “package.json” file.

npm init -y

Next, we’ll install Tailwind and its dependencies by running `npm install -D tailwindcss postcss autoprefixer`

npm install -D tailwindcss postcss autoprefixer

Once that finishes, we’ll create a default tailwind configuration file, and a postcss configuration file in a single step by running `npx tailwindcss init -p`

npx tailwind init -p

Let’s take a look at those files we just created. The “package.json” file has basic project information and dependencies. The “postcss.config.js” file configures the postcss processes, and we won’t need to do anything with it in this video. Then we have tailwind.config.js, which is what stores the tailwind configuration. This is the file that you’ll want to become very familiar with.

The next file is the tailwind “source.css” file. This file lets us add our directives and other things that get translated into the final tailwind.css file we reference in our html files. Create this file in the tailwind_theme folder and add the following lines to it.

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

Now, we’ll add a few lines to tailwind.config.js to tell it where to look for classes to add to the compiled CSS file./ This is essentially telling the compiler to look in the root of our project directory and in the _pginfo directory for HTML, JS, and CSS files.

content: [
       "./_pginfo/**/*.{html,js,css}",
       "./*.{html,js,css}",
   ],

While we are here, we’ll also modify the ‘extend’ section of tailwind.config.js so it can read Pinegrow’s design tab settings. These are commented for now, and we will uncomment them later once switch Pinegrow’s compiler to use the External Build Process.

extend: {
    //colors: pg_colors, //<-- Use the pg_colors for colors
    //fontFamily: pg_fonts, //<-- Use the pg_fonts for fonts
},

We now have all the pieces in place to compile our Tailwind CSS file, so let’s create a script in package.json to handle that for us. In the scripts section, just add this line to tell it the location of the input file, the output file, and that we want it to watch for changes. This is what you’ll run when you are actively working on your site.

"dev": "npx tailwindcss -i ./tailwind_theme/source.css -o ./tailwind_theme/tailwind.css --watch",

Add another script that will compile and minify the tailwind.css file when you are ready to deploy it.

"build": "npx tailwindcss -i ./tailwind_theme/source.css  -o ./tailwind_theme/tailwind.css  --minify",

Let’s also add another line that will let us easily launch Pinegrow’s browser sync service. After we save this, I’ll re-open my folder in VS Code, so it reads the NPM scripts and lets me run them through the GUI.

"pgserver": "browser-sync start --proxy 'http://127.0.0.1:40000'"

Test the Compiler

With all these steps completed, we are ready to test it all out. We’ll come back to our index.html and open a preview so we can see what it looks like. Now, let’s change the text-indigo-500 class to say text-red-500. You see right away that our text turns black. That’s because the CSS file won’t know what text-red-500 is until we compile it.

Let’s go down to NPM Scripts, click the run button next to the “dev” script, then wait for the compiler to do its thing. Once it’s done, we can refresh the page, and there you have it. The text is now red. If we want, we can leave that compiler running while we continue making changes, and it’ll pick up on them as we go. For example, we can change the class to text-yellow-500, and you’ll see it recognizing the change and building the new CSS file. One quick refresh later, and that’s all you need to do.

Switch Pinegrow’s Build Process to External

We are close to the end now! The next step is to tell Pinegrow to use the External Build Process. For that, we’ll open our project back up, open the index.html file, go to the design tab, and click the “compiler options” button. We select “external build process” from the dropdown and browse to that source.css file inside tailwind_theme. Once we hit the save button, you’ll see a message telling us to update the HTML pages to use the new tailwind.css file, but since we are outputting the file to the same place Pinegrow uses, we don’t need to worry about that. Just click on the “got it” button and get ready for the last thing on our list.

What Happened When We Switched Build Processes?

This last step is important, and again I need to show you some things that happened when we switch to the External Build Process.

First, that class.tracker.json file is now joined by used-classes.html. This is kind of a cool way for the compiler to be able to see all our classes listed inside one simple file. Next, Pinegrow added a min-height: 100vh; line to the source.css file. Some people argue that you shouldn’t use this, but I’ve never had an issue with it, and you can always remove it if you want to.

Uncomment the Pinegrow Color and Typography Lines

The most important thing, though, is that Pinegrow has added constants for colors and typography to tailwind.config.js. Remember when we added those commented lines earlier in the process? Now is our chance to uncomment them.

extend: {
    colors: pg_colors, //<-- Use the pg_colors for colors
    fontFamily: pg_fonts, //<-- Use the pg_fonts for fonts
},

Test Inside Pinegrow

Now, when we restart our Dev script, you’ll see that any changes we make inside Pinegrow get picked up by the compiler and applied right away. Let’s just go ahead and change our font color to text-green-500 as a demonstration. And there it is.

Add First-Party Tailwind Plugins

Now, you have everything all configured and ready to go. But wait a minute… Tailwind offers some pretty incredible plugins and I think it’s worth at least taking a look at some of the first-party plugins. First, we need to install them. I’m just going stop our compiler and combine the installation commands all into a single line here.

(Note: I have not included the aspect-ratio plugin since it’s now included in Tailwind and the plugin is deprecated.)

npm install -D @tailwindcss/typography @tailwindcss/forms @tailwindcss/line-clamp @tailwindcss/container-queries

Then, we’ll add the required lines to the plugins section of tailwind.config.js

plugins: [
    require("@tailwindcss/typography"),
    require("@tailwindcss/forms"),
    require("@tailwindcss/line-clamp"),
    require("@tailwindcss/container-queries"),
],

After we save the file, let’s just quickly run the dev script to make sure we don’t have any errors. And that’s it, now you are ready to use all the cool stuff that those plugins offer!

Conclusion

As with most tutorials, this took a lot longer than necessary because I stopped to explain everything. In reality, it takes less than 5 minutes from start to finish, and it’s even quicker if you just create a template project and reuse it over and over again.

If you have any questions or if you think I missed something, leave a comment below.

And, as always, if you found this video helpful, please hit that like button and subscribe to the channel.

I’ll see you next time!