DEV Community

Matt Lehrer
Matt Lehrer

Posted on

How to Setup TailwindCSS for a Custom Ghost Theme

Ghost has a ton going for it. But existing themes are never exactly right and I wanted to be able to make changes with TailwindCSS and couldn't find a fresh start -- despite finding others looking for this, too. If you're in the same position, this post is for you.

I use the official Ghost Starter Theme as a jumping off point, though you should be able to do this with any existing theme.

You'll need the Ghost CLI installed.

npm install ghost-cli@latest -g

Start by creating a fresh directory.

mkdir ghost-project && cd "$_"

Then install Ghost locally.

ghost install local

After the installation is done, you'll have a running ghost instance at http://localhost:2368

Next create a new repository based on the Ghost Starter Theme using the "Use this template" green button on Github.
Use this template

cd into the themes directory and clone the new repo, with your username and the name of the repo:

cd content/themes
git clone<your-github-username/<your-new-repo-name>.git ghost-starter-with-tailwind

The default Casper theme will be in that directory as a sibling, if you want to see how that theme handles anything.

The Ghost Starter Theme uses yarn, so use that to install dependencies. cd into your new theme directory and then run yarn:

cd ghost-starter-with-tailwind

This is a good time to change the name of the theme to whatever you'd like. The name field at the top of the package.json ('ghost-starter-theme' when you open the file) is what shows up in Ghost's admin interface.

You can now install and setup Tailwind.

yarn add tailwindcss
npx tailwindcss init

Add the Tailwind base styles to ./assets/css/screen.css:

/* assets/css/screen.css */

/* ... */

/* Base components */
@import "vars.css";
@import "components/global.css";
@import "components/forms.css";
@import "components/buttons.css";

/* Ghost components */
@import "ghost/header.css";
@import "ghost/content.css";
@import "ghost/readmore.css";
@import "ghost/members.css";
@import "ghost/errors.css";
@import "ghost/footer.css";
@import "ghost/badge.css";

/* Tailwind - add this part */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

/* ... */

As you replace styles with Tailwind classes, you can remove the other imports but leave them there for now.

The Starter uses Gulp and gulp-postcss, so we'll roughly follow that part of the Tailwind installation instructions:

// gulpfile.js

// import tailwind at the top of the file
const tailwind = require('tailwindcss')

// ...

// add tailwind to the css processors list, around line 43:
function css(done) {
    var processors = [
        tailwind(), // add this

    // ...

Next, restart ghost to make sure we're catching all the new files and the name change on the theme, if you made one. It shouldn't matter what your working directory is. You can run this from the theme directory.

ghost restart

Then start all the theme file watchers, so that changes to css and the handlebars files are picked up by Ghost. This you have to run from the theme directory (/content/themes/ghost-starter-with-tailwind or whatever you named it).

yarn dev

Setup Ghost admin with a name for the admin and the blog, an email and a password at http://localhost:2368/ghost and then hit skip at the bottom of the next page when it asks to invite teammates.

Account setup


Almost done now. Go into Ghost's settings and activate the new theme. Click into Settings > Design.
Design settings
And then all the way at the bottom of the Design Settings page, click activate on the new theme.
Activate theme

Finally, you can start adding Tailwind classes to your handlebars templates. If something doesn't work quite right, try removing CSS and imports from screen.css. Your changes should be picked up by the watchers, but there's no autoreload in the browser. So refresh after saving any changes.

This should get you started. I have the code to this point on Github.

I'll follow up with another post on how I converted the existing CSS to Tailwind, adding Tailwind's typography plugin for a good starting point for post pages, and purging unused CSS on Ghost Pro, which required manual purging when I used it.

Top comments (6)

jpollone profile image
Joseph Pollone

Thanks for the write-up, Matt. Just wanted all to know that this is relevant as of today (MAR 2021) with Ghost v4.1.0 and TailwindCSS v2.4.0.

For those of you new to dependencies, just be aware that you may need to adjust your system according to the package's requirements. Watch the console and correct accordingly.

For example, when I ran yarn it wanted to use an older version of NodeJS, so I installed v12.13.0 that was expected via the error message. (I use NVM so it's quite easy to do.)

One notable error was an incompatibility running yarn dev with Tailwind:
Error: PostCSS plugin tailwindcss requires PostCSS 8.

Follow these instructions to re-install Tailwind's compatibility build.

tetrisiq profile image

Thanks for this Tutorial.
I have added css(done) to the hbs function in gulbfile.js.
Otherwise, only used tailwind CSS classes are included. Newly added classes are only included when I restart yarn dev.
So the hbs funktion looks like this:

function hbs(done) {
        src(['*.hbs', '**/**/*.hbs', '!node_modules/**/*.hbs']),
    ], handleError(done));
Enter fullscreen mode Exit fullscreen mode
defite profile image
Nikita Makhov • Edited

It will not work without including *.hbs files to content section in tailwind.config.js like so:

module.exports = {
    content: ["./*.hbs", "./**/*.hbs"],
    theme: {
        extend: {},
    plugins: [],
Enter fullscreen mode Exit fullscreen mode
henriandrade profile image
henriandrade • Edited

I am having trouble to debug using VSCode with this environment. Anyone had success running the VSCode debugger?

alessandrobelli profile image
Alessandro Belli

Thanks for the tutorial! To make it work I had to install the "official" post-css, not only the gulp one.

cuongtran profile image
Cuong Tran

Hi Matt, the theme will purge unused CSS automatically when I run yarn dev?