Custom theme CSS not updating locally

Developer help Installation
1

Hi, everyone.

I’m designing a custom theme for Ghost, running it locally. Everything was running fine for a while. I was updating the theme locally, seeing my changes, and uploading the theme zip to our remote server.

After I updated ghost locally (using ghost update) my local CSS changes are not compiling to the “built” directory, so no changes are seen in my browser.

Some notes:

  • I’m on macOS
  • Local version of Ghost is 5.116.2
  • Running with standard port (2368)
  • I begin Ghost normally using ghost start and when I run ghost ls everything looks fine, showing it’s running in development mode
  • No theme updates compile for my browser (even the default “source”) so it’s not an issue with my theme
  • I’ve tried multiple browsers, but I know that’s also not an issue because after I update CSS and save it, the CSS version number doesn’t refresh (so I know it’s not being updated)
  • There are no console/terminal errors

So, Ghost is running fine. I can use the admin UI to successfully mange the build. I can see the site. Everything works, except that I can no longer update my (or any) theme.

I’d love any advice y’all might have.

Thanks in advance.

2

just to clarify, are you saying that the built css files for your theme present in your local environment are not the same versions that you can see in the theme directory on your production server?

3

No. Sorry for that confusion.

I’m saying that when I make changes to my source CSS files:

/my-theme/assets/css/*

They’re not compiling on save to:

/my-theme/assets/*

So here’s my process:

  1. Run ghost start (see screenshot that shows it’s running)
  2. Make edits to CSS and save them
  3. Refresh the page in my browser with no changes made

I’m not too familiar with Gulp, but it’s my understanding that it’s doing the compiling in real time while Ghost is running. But if I run gulp --version I get this:

CLI version: 3.0.0
Local version: 5.0.0

Screenshot of terminal of the results of “ghost ls” showing version 5.116.2 running in development mode at port 2368.

4

ah I see - difficult to be sure without seeing the how the theme is organised, but many themes have a build step that minimises the css. Your theme will then contain a link to the minimized file, rather than the file you change when updating the theme - something like
<link rel="stylesheet" type="text/css" href="{{asset "built/css/main.css"}}">

is your theme based on one of the Ghost standard themes? If so you can try running gulp from the root of the theme directory to see if this starts a file watcher (if set up properly, the file watcher will automatically minimise the css/js as you work). If it doesn’t work you could perhaps post the contents of your gulpfile.js and package.json so we can see how the project was set up.

5

Confirmed that the theme is properly linking to the minimized assets (CSS and JS). And, yes, it’s based on a standard Ghost theme. But I don’t recall which one.

The thing to note is that it was working fine. Everything was linked and I was updating CSS with no trouble. Then after I updated Ghost it stopped compiling to the minimized CSS. If I update and save, I can see that the minimized file has not been updated (based on timestamp and version number not being refreshed in the source in my browser). This tells me the compiler isn’t functioning.

Is it necessary to run gulp watch in order to have the changes compile? If I do run that, I get an error:

Error: Cannot find module 'ordered-read-streams’

Maybe there’s a compatibility issue between Gulp and Node? I’m on Node 22.14.0, but as I noted above I’m not sure why gulp --version returns two versions (CLI 3.0.0 and local 5.0.0).

So it’s probably an issue with Gulp throwing the error. Any idea how to fix that?

6

I haven’t used a Ghost theme for a while but I think the default action defined in gulpfile.js is to watch for changes to hbs, js and css

just type gulp to run it in that case. You can use gulp --tasks to see what tasks have been defined in the gulpfile.js

the --version message is normal

7

Thank you so much for all of your help, @NickAbs. While you didn’t explicitly give me the solution, you did help move me through a path to find it.

I simply had to run this: npm install ordered-read-streams --save-dev

That installed the module for me. Now when I run gulp it runs build, serve, and watcher, which compiles on save.

Be well.

2 Likes