US Edge Cache Warmer

A Cloudflare Worker that pre-warms the cache for a URL across all major US edge locations. This tool helps ensure your content is cached and ready to serve in all US regions, improving load times for your users.

Features

• Caches a target URL on all major US Cloudflare edge locations
• Accepts target URLs via query parameters or POST request
• Provides detailed per-region caching status reports
• Can be scheduled to run automatically using Cloudflare's Cron Triggers

Prerequisites

• Node.js (version 14 or later)
• Wrangler CLI (Cloudflare's command-line tool for Workers)
• A Cloudflare account with Workers enabled

Installation & Deployment

1. Install Wrangler

If you haven't already installed Wrangler, do so with npm:

npm install -g wrangler

2. Log in to your Cloudflare account

Authenticate Wrangler with your Cloudflare account:

wrangler login

Follow the prompts to log in through your browser.

3. Create a new Worker project

Create a new directory for your project and initialize it:

mkdir cache-warmer
cd cache-warmer

4. Create your Worker script

Create a file named index.js and paste the provided Worker code into it.

5. Create a wrangler.toml configuration file

Create a wrangler.toml file in your project directory with the following content:

name = "cache-warmer"
main = "index.js"
compatibility_date = "2023-10-16"

[triggers]
# Cron trigger example: run daily at 2:00 AM UTC
# Uncomment the line below to enable
# crons = ["0 2 * * *"]

6. Deploy the Worker

Deploy your Worker to Cloudflare:

wrangler deploy

After deployment, Wrangler will output the URL where your Worker is available.

Setting Up a Cron Trigger

To run the cache warmer automatically on a schedule, you can use Cloudflare's Cron Triggers.

Using wrangler.toml (Recommended)

1. Edit your wrangler.toml file and uncomment the crons line:

[triggers]
crons = ["0 2 * * *"]  # Run at 2:00 AM UTC every day

2. The cron format is "minute hour day month day_of_week". Some examples:

   • "0 2 * * *" - Run at 2:00 AM UTC every day
   • "0 */6 * * *" - Run every 6 hours
   • "0 0 * * MON" - Run at midnight every Monday

3. Redeploy your Worker:

wrangler deploy

Using Cloudflare Dashboard

Alternatively, you can set up cron triggers via the Cloudflare Dashboard:

1. Go to the Cloudflare Dashboard
2. Navigate to Workers & Pages
3. Select your cache-warmer Worker
4. Go to the "Triggers" tab
5. Click "Add Cron Trigger"
6. Enter your desired cron schedule
7. Click "Add"

Example: Warming Cache for Your Homepage Daily

A common usage is to set up a daily cron job to pre-warm the cache for your website's homepage.

Option 1: Using the Scheduled Event Handler

To automate the process, you can modify your worker to handle scheduled events:

1. Update your index.js to add a scheduled event handler:

export default {
  // Keep your existing fetch handler
  async fetch(request, env, ctx) {
    // Existing code...
  },
  
  // Add a scheduled handler to warm cache for a specific URL
  async scheduled(event, env, ctx) {
    const targetUrl = "https://your-website.com";
    
    // Process all regions in parallel
    const results = await Promise.allSettled(US_REGIONS.map(async (region) => {
      return await cacheInRegion(targetUrl, region);
    }));
    
    console.log(`Cache warming completed for ${targetUrl}`);
  }
};

2. Update your wrangler.toml to enable the cron trigger:

name = "cache-warmer"
main = "index.js"
compatibility_date = "2023-10-16"

[triggers]
crons = ["0 7 * * *"]  # Run daily at 7:00 AM UTC (before peak traffic)

3. Deploy with the updated configuration:

wrangler deploy

Option 2: Using Another Worker or Service

You can also trigger your cache warmer externally:

1. Set up a curl command in any server cron job:

curl -X POST \
  https://cache-warmer.[your-worker-subdomain].workers.dev/ \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-website.com"}'

2. Or use a third-party cron service like cron-job.org to call your worker URL at scheduled times.

Manual Usage

Via GET Request

You can trigger the cache warmer by sending a GET request with a url parameter:

https://cache-warmer.[your-worker-subdomain].workers.dev/?url=https://example.com/page-to-cache

Via POST Request

Alternatively, you can send a POST request with a JSON body:

curl -X POST \
  https://cache-warmer.[your-worker-subdomain].workers.dev/ \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page-to-cache"}'

Response Format

The Worker will respond with a JSON object containing:

• url: The URL that was cached
• cached: Whether caching was attempted
• regionResults: Array of results for each region
  • region: The region code
  • success: Whether the request to that region succeeded
  • status: HTTP status code
  • error: Error message if the request failed

Example response:

{
  "url": "https://example.com",
  "cached": true,
  "regionResults": [
    {
      "region": "IAD",
      "success": true,
      "status": 200,
      "error": null
    },
    // Additional regions...
  ]
}

Troubleshooting

• HTTP 400 Errors: Check that your URL is properly formatted and includes the protocol (http:// or https://).
• Authentication Issues: If you need to cache authenticated content, you'll need to modify the Worker to include authentication headers.
• Deployment Failed: Ensure you're logged in via wrangler login and have the proper permissions on your Cloudflare account.
• Cron Not Running: Verify your cron expression is valid and check the "Logs" section in the Cloudflare Dashboard for your Worker.