Hosting a Hugo site on a Cloudflare Worker

[tyco]

Following a discussion on hosting Hugo on a Cloudflare worker, @jmooring came up with an excellent solution.

Here’s an example project hosted on a Cloudflare Worker:

GitHub - jmooring/hosting-cloudflare-worker: This is a test of hosting a Hugo site on a...

This is the build script:

build.sh

And the wrangler.toml file

wrangler.toml

Those are the only two files you need to copy to your project and configure to your liking. For example–

• change Dart SASS version or if you don’t transpile SASS to CSS, you can remove Dart SASS code from the build.sh file.
• change the time zone.
• change Hugo version
• change Node JS version

[svenvg93]

I was able to get the deployment working without a custom build script by using the following simplified wrangler.jsonc configuration:

{
  "name": "example-com",
  "compatibility_date": "2025-07-20",
  "assets": {
    "directory": "./public",
    "html_handling": "auto-trailing-slash",
    "not_found_handling": "404-page",
    "run_worker_first": false
  },
  "build": {
    "command": "hugo build --gc --minify",
  },
  "workers_dev": true,
  "preview_urls": true
}

Not sure it will work for every environment as I have mine themes defined in go modules

[tyco]

This example is shared by a Hugo support/maintainer person. So, for a user, it is the way I would recommend to go with.

[jmooring]

The build script:

1. Installs a specific version of Hugo
2. Installs a specific version of Dart Sass to transpile Sass to CSS
3. Sets the system timezone
4. Ensures that Page.GitInfo returns the expected results
5. Addresses https://github.com/gohugoio/hugo/issues/9810

In my view all but #2 are required for every site.

[dindinet]

@jmooring Hi Jo I had a go with your build.sh script but fails.
I get this in the cloudflare worker build logs:

stderr: ‘/bin/sh: 1: ./build.sh: Permission denied’,

Have I missed something real simple?

[tyco]

@dindinet

stderr: ‘/bin/sh: 1: ./build.sh: Permission denied’,

Did you copy the code directly from Joe’s file or the file itself? See Hugo support in Cloudflare Workers - #6 by tyco and Hugo support in Cloudflare Workers - #7 by jmooring.

[dindinet]

I copied the code from hosting-cloudflare-worker/build.sh at main · jmooring/hosting-cloudflare-worker · GitHub raw and pasted it into a file build.sh in my project.

[dindinet]

Doh!
I I did a
git add --chmod=+x build.sh
instead of
chmod +x build.sh

All good now

[jmooring]

In our Host on Cloudflare documentation I’ve change the build command from this:

[build]
command = "./build.sh'"

To this:

[build]
command = "chmod a+x build.sh && ./build.sh"

That makes the permissions of the file in the repository irrelevant.

[tifenak]

I tried the worker, but I have to remember every time to rebase my project before pushing changes (mostly markdown content).

[pawelgrzybek]

High chance that what @jmooring is suggesting here is better, but I found a lot simpler way to ensure that the CF is running on the latest version of Hugo.

Adding HUGO_VERSION to the build env var config does the trick.

[jmooring]

That gives you the standard edition, not the extended one. Keep in mind that while you don’t need the extended version for WebP encoding anymore since v0.153.0, you still need it to transpile Sass to CSS with the built-in LibSass tool. Unless you’re 100% sure which transpiler your template is using, it’s usually much safer to just run the extended edition and avoid the headache.

Getting the right version and edition running is really only half the battle, though. If you’re setting this up on Cloudflare for the first time, I definitely recommend checking out the official guide at Host on Cloudflare to make sure everything else is dialed in correctly. The devil is in the details…

[pawelgrzybek]

Thank you so much for the clarification. Your guide is phenomenal, thank you for that. Probably I never hit any of the limitation you mentioned above because my site is so simple and I don’t use Sass on my templates, just pure CSS.

What is explained on your guide should also be mirrored here imo Web applications · Cloudflare Workers docs Would you mind if I trigger a PR to the CF docs that suggest changes based on your guide? Maybe slightly edited to better suit CF docs. Of course I will link you to it…

[pawelgrzybek]

I just did a quick experimentation, and looks like sass in version 1.97.3 also comes built-in in CF Workers runtime now. That should be enough to fulfil all the cases unless someone really needs this part of your script.

 # Configure Git
  echo "Configuring Git..."
  git config core.quotepath false
  if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
    git fetch --unshallow
  fi
  

Here is the screenshot from the CF logs view.

This is sass --version but my screenshooting tool merged double hyphen into en-dash

[pawelgrzybek]

I just run a quick dirty script to output whats already on the CF runtime, maybe someone is going to find it helpful.

Cloudflare Build Environment CLIs

[jmooring]

I might be overly cautious, but I don’t like leaving a build environment to chance. Relying on a service provider’s default tools is a moving target; specifying exact versions ensures I’m not stuck with an outdated toolset or blindsided by a breaking update I didn’t plan for.

At the time I wrote the guide, if I wanted to specify versions in one place, the only way I could do it was within a build script.

[pawelgrzybek]

I totally agree with your point. For simpler and less critical projects, it can be sufficient to just specify the desired version. Sass has a great history of backward compatibility, and also not every single project uses Sass. Modern CSS with custom properties and nesting gave me all I used Sass for, and now I just use pure CSS.

In terms of specifying the exact version of Hugo, yeah, I think CF added an ability to add build vars only recently.

I also tested working with .GitInfo and that also worked without any additional changes, but I have a very little understanding of this part so I’m sure your script is there for a good reason.

Thank you for help @jmooring, I mentioned this conversation and pros and cons of both approaches on my post.

Deploy Hugo site to Cloudflare Workers | pawelgrzybek.com

[jmooring]

@pawelgrzybek

.GitInfo

The Git configuration in the build script addresses (a) the fact that CF performs shallow clones, and (b) a known issue related to file names (GitInfo unset when file path contains bytes > 0x80 · Issue #9810 · gohugoio/hugo · GitHub).

[pawelgrzybek]

Thank you!

[markupandmatcha]

this is a really tidy setup — nice to see it documented properly.

we’ve been using Netlify for most of our client sites at the studio and it’s genuinely hard to beat for zero-config deployments. but the Cloudflare Workers approach is interesting for cases where you want edge performance without the Netlify overhead on the free tier (their bandwidth limits can sneak up on you on image-heavy sites).

one thing worth noting for anyone comparing options: Netlify and Vercel both auto-detect Hugo projects and handle the build for you — so there’s basically no config file to write at all, which is nice if you just want to get something live fast. the Cloudflare Worker approach here is more manual but gives you way more control and the edge distribution is genuinely fast.

for personal projects or simple blogs i’d still say Netlify is the path of least resistance. but for something with heavier traffic or global audiences, this Worker approach looks worth the extra setup.

has anyone run into issues with the Dart Sass installation step taking too long on cold builds? that’s been our main friction point with custom build scripts on similar setups.