Cloudflare Pages

Cloudflare is a cloud solutions provider with a huge proprietary content delivery network (CDN). Like Netlify or Vercel, Cloudflare Pages makes the deployment process flexible and easy. You can add a GitHub repo to the service and build & host Zola-based websites after each PR automatically.

🔗Step-by-step

  1. Sign in or create a new Cloudflare account and choose "Pages" on the right nav column
  2. Press the button "Create a project"
  3. Select the GitHub repo that contains your Zola website and connect it to Cloudflare Pages
  4. Click "Begin setup"
  5. Enter your project name. Keep in mind that if you would like to use the default Pages domain (pages.dev), this will be your website's future URL ("yourprojectname.pages.dev"). Additionally, select a production branch.
  6. In Build settings, select Zola as the Framework preset. Build command and Build output directory will be filled automatically.
  7. Toggle Environment variables below and add ZOLA_VERSION as a variable name. Use 0.17.2 or a different Zola version as the value.
  8. Finally, save and deploy.

Your website is now built and deployed to Cloudflare's network! You can add a custom domain or modify settings in the Pages dashboard.

You may find documentation and guides like Getting started with Cloudflare Pages and Deploying Zola with Cloudflare Pages in the Developers portal.

🔗Handling preview deployments

When working with Cloudflare Pages, you'll often use preview deployments for testing changes before merging to your main branch. By default, these preview deployments use different URLs (like https://your-branch-name.your-project.pages.dev), which can cause issues with asset loading if your base_url is hardcoded in your config.toml.

To fix this, modify your build command in the Cloudflare Pages configuration to dynamically set the base URL depending on the environment:

if [ "$CF_PAGES_BRANCH" = "main" ]; then zola build; else zola build --base-url $CF_PAGES_URL; fi

This command:

  • Uses your config.toml base_url when building from the main branch
  • Uses the preview deployment URL (automatically provided by Cloudflare Pages as $CF_PAGES_URL) for all other branches

🔗Troubleshooting

Some tips to help troubleshoot issues getting started with Cloudflare Pages.

🔗zola: not found

If you see build output that resembles something like this:

23:03:54.609	> build
23:03:54.609	> zola build $BUILD_OPTS && npx tailwindcss -i ./public/input.css -o ./public/style.css -m
23:03:54.609
23:03:54.621	sh: 1: zola: not found
23:03:54.635	Failed: Error while executing user command. Exited with error code: 127
23:03:54.644	Failed: build command exited with code: 1
23:03:55.699	Failed: error occurred while running build command

Then it might be due to an outstanding issue. There are currently two recommended workarounds:

🔗Change the build system version to v1

From within the workers & pages dash, go to the following: Settings > Builds & deployments > Build system version > Configure build system

Then select v1 and save.

🔗Or use UNSTABLE_PRE_BUILD environment variable + asdf

From within the workers & pages dash, do the following: Settings > Environment variables > Edit variables

And add an environment variable UNSTABLE_PRE_BUILD, with the following value and save.

asdf plugin add zola https://github.com/salasrod/asdf-zola && asdf install zola 0.18.0 && asdf global zola 0.18.0