Zine

Deploying on Cloudflare Pages

About

This guide assumes that you're already familiar with using Cloudflare Pages and the Wrangler CLI. Please refer the official Cloudflare Pages documentation for more info.

Getting Started

To get started you will need to first create a new Cloudflare Pages project.

shell

$ wrangler pages project create PROJECT_NAME

This will create a new Cloudflare Pages project that you can deploy to, which can be done in two different ways.

2. Use GitHub Actions

This method uses GitHub Actions to build the site and then uploads the output to Cloudflare Pages (instead of GitHub Pages).

This section assumes that you're already familiar with GitHub Actions. Please refer the official GitHub Actions documentation for more info.

GitHub Actions runner have an inherent overhead and, since Zine is a collection of tools that gets compiled on-demand, your runner will need to do some work that wounldn't be necessary with a single-executable tool.

Luckly, the build will be cached automatically by using mlugg/setup-zig.

This site currently builds in 25-35 seconds, of which 12 are spent setting up Zig, and 2 for the actual site build (the rest is GitHub Pages overhead).

Once we have created our Cloudflare Pages project, we will need a few things from Cloudflare:

Replace ACCOUNT_ID with your Cloudflare Account ID and add your API key as a GitHub Actions secret. In the example below, this would be set to CLOUDFLARE_API_TOKEN.

.github/workflows/cf-pages.yml

name: cloudflare pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Change if you need git info

      - name: Setup Zig
        uses: mlugg/setup-zig@v1
        with:
          version: 0.13.0
          
      - name: Build
        run: zig build --summary new
          
      - name: Deploy
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ACCOUNT_ID
          projectName: PROJECT_NAME
          directory: ./zig-out
          # Optional: Adds GitHub deployments support
          githubToken: ${{ secrets.GITHUB_TOKEN }}
          

NOTE

If you want to have your deployments populate the GitHub deployments menu, you must also enable your Action to have read and write permissions.

This can be by going to Settings -> Actions -> General -> Workflow Permissions.

2. Build locally and deploy directly with wrangler

To publish from your computer you will need fist to build your Zine site, and then upload the output to Cloudflare Pages using wrangler.

shell

$ zig build 
$ wrangler pages deploy ./zig-out --project-name PROJECT_NAME

Warning

Currently Zine doesn't clean zig-out/ across rebuilds so you will have to do it manually.