Cloudflare Cheatsheet

Production cheatsheet from ActiveWizards deployment (CF Pages + Functions + DNS).

Wrangler CLI

# Deploy a static site (pre-built)
npx wrangler pages deploy dist --project-name=my-site --branch=main

# Deploy with dirty git state (CI/local)
npx wrangler pages deploy dist --project-name=my-site --commit-dirty=true --branch=main

# Set secrets (not visible in dashboard)
npx wrangler pages secret put MAILGUN_API_KEY

# List projects
npx wrangler pages list

# Tail logs (Functions)
npx wrangler pages deployment tail --project-name=my-site

Deploy Script Pattern (multi-site)

#!/usr/bin/env bash
set -euo pipefail
SITE_DIR="$(cd "$(dirname "$0")" && pwd)/site"

deploy_astro() {
    local site="$1" project="$2" branch="${3:-staging}"
    (cd "${SITE_DIR}/${site}" && npm run build)
    npx wrangler pages deploy "${SITE_DIR}/${site}/dist" \
      --project-name="${project}" --commit-dirty=true --branch="${branch}"
}

deploy_static() {
    local site="$1" project="$2"
    npx wrangler pages deploy "${SITE_DIR}/${site}" \
      --project-name="${project}" --commit-dirty=true --branch=main
}

case "${1:-}" in
    staging)  deploy_astro my-site my-project staging ;;
    prod)     deploy_astro my-site my-project main ;;
    *)        echo "Usage: $0 [staging|prod]"; exit 1 ;;
esac

_redirects File

Place in public/_redirects (copied to dist/ on build).

Format

<from> <to> <status>

Examples

# Simple redirect
/old-url /new-url 301

# With trailing slash normalization
/contact/ /contact-us/ 301

# Splat (wildcard)
/old-blog/* /blog/:splat 301

# SPA fallback (DON'T use for SSG sites)
/* /index.html 200

Rules

• Max 2000 rules (hard limit)
• Processed top to bottom, first match wins
• Splats: * captures everything, :splat inserts it in destination
• Placeholders: /blog/:slug matches /blog/anything
• Static files take priority over redirects (a redirect won't override an actual file)
• Duplicate rules are silently ignored (no error, first one wins)

Production note

AW site has 804+ redirect rules for MODx migration. Bulk-generated by scripts/migration_decision.py.

Pages Functions

Files in functions/ directory map to API routes:

Basic Function

interface Env {
  MAILGUN_API_KEY: string;
  MAILGUN_DOMAIN: string;
  NOTIFICATION_EMAIL: string;
}

export const onRequestPost: PagesFunction<Env> = async (context) => {
  const { request, env } = context;
  const formData = await request.formData();

  const name = formData.get("name")?.toString().trim() || "";
  const email = formData.get("email")?.toString().trim() || "";

  if (!name || !email) {
    return new Response(JSON.stringify({ error: "Missing fields" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  // Fire-and-forget with waitUntil (response returns immediately)
  context.waitUntil(
    fetch(https://api.mailgun.net/v3/${env.MAILGUN_DOMAIN}/messages, {
      method: "POST",
      headers: { Authorization: "Basic " + btoa(api:${env.MAILGUN_API_KEY}) },
      body: buildFormData(name, email, env),
    }).catch((err) => console.error("Mailgun failed:", err))
  );

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
};

Key patterns

• context.waitUntil(): Fire-and-forget async work. Response returns immediately while the email sends in the background.
• onRequestPost / onRequestGet: Method-specific handlers.
• onRequest: Catches all methods.
• Env typing: PagesFunction gives typed access to context.env.

Dual response (JSON + redirect)

function jsonOrRedirect(request: Request, data: object, redirectUrl: string): Response {
  const accept = request.headers.get("Accept") || "";
  if (accept.includes("application/json")) {
    return new Response(JSON.stringify(data), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    });
  }
  return Response.redirect(new URL(redirectUrl, request.url).toString(), 302);
}

This handles both fetch() (returns JSON) and

npx wrangler pages deploy dist --project-name=my-site --branch=staging

npx wrangler pages secret put MAILGUN_API_KEY
# Prompts for value (not stored in shell history)

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

/fonts/*
  Cache-Control: public, max-age=31536000, immutable

/*.css
  Cache-Control: public, max-age=31536000, immutable

[[kv_namespaces]]
binding = "CACHE"
id = "abc123"

# UFW rules on origin server — allow only Cloudflare IPs on 80/443
# See https://www.cloudflare.com/ips/ for current list