Deployment Guide

Deploy experiments to Cloudflare Workers using click-to-deploy or manual methods

Every experiment in this repository can be deployed independently to Cloudflare Workers. This guide covers all deployment methods and configuration steps.

Quick Deploy (Click-to-Deploy)

The fastest way to deploy any experiment is using Cloudflare’s one-click deployment:

1. Choose an experiment

   Navigate to any experiment page and click the “Deploy to Cloudflare Workers” button.

   Each experiment README includes a deploy button linking to its source code.

2. Authenticate with Cloudflare

   Sign in to your Cloudflare account or create one if you don’t have an account.

   The deployment system will request permissions to deploy Workers on your behalf.

3. Configure resources

   Some experiments require additional resources:

   • D1 databases: Created automatically during deployment
   • KV namespaces: Created automatically
   • R2 buckets: Created automatically
   • Browser Rendering: Enabled automatically (requires plan upgrade)
   • Workers AI: Enabled automatically (requires plan upgrade)

   The deployment wizard guides you through any required setup.

4. Deploy

   Click the final deploy button. Your Worker will be deployed to a *.workers.dev subdomain.

   The deployment typically completes in 10-30 seconds.

Deployment URL Format

Click-to-deploy URLs follow this pattern:

https://deploy.workers.cloudflare.com/?url=https://github.com/{owner}/{repo}/tree/{branch}/experiments/{experiment-name}

Example:

https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/experiments/ai-website-summary

To deploy from your own fork, replace shrinathsnayak with your GitHub username in the deployment URL.

Manual Deployment

For more control or local development, deploy manually using Wrangler CLI.

Prerequisites

Install the required tools:

# Install Node.js 18+ (via nvm recommended)
nvm install 18
nvm use 18

# Install Wrangler CLI globally
npm install -g wrangler

# Authenticate with Cloudflare
wrangler login

Clone the repository:

git clone https://github.com/shrinathsnayak/cloudflare-experiments.git
cd cloudflare-experiments

Basic Experiments

Deploy experiments with no external dependencies (most experiments):

# Navigate to experiment directory
cd experiments/is-it-down

# Install dependencies
npm install

# Test locally
npm run dev
# Visit http://localhost:8787

# Deploy to production
npm run deploy
# or: wrangler deploy

Your Worker will be deployed to https://{experiment-name}.{your-subdomain}.workers.dev.

Basic experiments include: Is It Down, Where Am I, Website Metadata Extractor, Dependency Analyzer, Website to API, URL DNS Lookup, Website DevTools Inspector, AI Bot Visibility, Website to llms.txt

Workers AI

Experiments using Workers AI require additional setup:

cd experiments/ai-website-summary
npm install

# Workers AI is automatically bound in wrangler.json
# No additional configuration needed

# Test with remote AI (local dev doesn't support AI)
npm run dev -- --remote

# Deploy
npm run deploy

Workers AI requires the Workers Paid plan ($5/month). The first 10,000 AI requests per day are included.

Experiments using Workers AI:

• AI Website Summary
• GitHub Repo Explainer

Browser Rendering

Deploy experiments that capture screenshots:

cd experiments/screenshot-api
npm install

# Browser Rendering requires remote mode for local testing
npm run dev -- --remote

# Deploy
npm run deploy

Browser Rendering requires the Workers Paid plan. Pricing is per browser session.

The Browser binding is automatically configured in wrangler.json:

{
  "browser": {
    "binding": "BROWSER"
  }
}

D1 + KV

Deploy experiments with database storage:

cd experiments/link-shortener
npm install

# 1. Create D1 database
wrangler d1 create link-shortener-db
# Copy the returned database_id

# 2. Update wrangler.json with the database_id
# Replace 00000000-0000-0000-0000-000000000000 with your database_id

# 3. Create KV namespace
wrangler kv namespace create LINKS_CACHE
# Copy the returned id

# 4. Update wrangler.json with the KV namespace id

# 5. Run migrations locally
npm run db:migrate:local

# 6. Test locally
npm run dev

# 7. Run migrations on production
npm run db:migrate

# 8. Deploy
npm run deploy

wrangler.json structure:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "link-shortener-db",
      "database_id": "your-database-id-here"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "LINKS_CACHE",
      "id": "your-kv-namespace-id-here"
    }
  ]
}

D1 and KV are included in the Workers Free plan with usage limits. Paid plan removes limits.

R2 Storage

Deploy experiments with object storage:

cd experiments/r2-storage
npm install

# 1. Create R2 buckets in Cloudflare Dashboard
# - r2-storage-bucket (private)
# - r2-storage-public (public)

# 2. Enable public access on r2-storage-public:
# Dashboard → R2 → r2-storage-public → Settings → Enable Public Access
# Copy the public URL (e.g., https://pub-xxxxx.r2.dev)

# 3. Update wrangler.json with bucket names
# Set PUBLIC_BUCKET_URL in vars section

# 4. Test with remote R2 (local mode doesn't support public URLs)
npm run dev -- --remote

# 5. Deploy
npm run deploy

wrangler.json structure:

{
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "r2-storage-bucket"
    },
    {
      "binding": "PUBLIC_BUCKET",
      "bucket_name": "r2-storage-public"
    }
  ],
  "vars": {
    "PUBLIC_BUCKET_URL": "https://pub-xxxxx.r2.dev"
  }
}

R2 requires the Workers Paid plan. Storage is charged per GB-month, with no egress fees.

Custom Domains

Add a custom domain to any deployed Worker:

1. Add domain to Cloudflare

   Ensure your domain is already added to Cloudflare and using Cloudflare nameservers.

2. Navigate to Workers & Pages

   In the Cloudflare dashboard:

   1. Go to Workers & Pages
   2. Select your deployed Worker
   3. Click the Triggers tab
3. Add custom domain

   1. Click Add Custom Domain
   2. Enter your subdomain (e.g., api.example.com)
   3. Click Add Custom Domain

   Cloudflare automatically creates DNS records and provisions SSL certificates.

Environment Variables

Some experiments require environment variables. Set them in the dashboard or via Wrangler:

Dashboard

1. Go to Workers & Pages
2. Select your Worker
3. Go to Settings → Variables
4. Add variables (Plain text or Secret)
5. Click Save

Wrangler CLI

Set secrets via Wrangler:

# Set a secret (encrypted)
wrangler secret put API_KEY
# Enter the value when prompted

# Set a plain text variable (in wrangler.json)
{
  "vars": {
    "PUBLIC_URL": "https://example.com"
  }
}

Deployment Checklist

1. Verify local functionality

   npm run dev
   # Test all endpoints
   
2. Check TypeScript

   npm run build
   # or: tsc --noEmit
   
3. Create required resources

   • D1 databases
   • KV namespaces
   • R2 buckets
   • Set environment variables
4. Run migrations (if applicable)

   npm run db:migrate
   
5. Deploy

   npm run deploy
   
6. Test production

   curl https://your-worker.workers.dev
   

Troubleshooting

Deployment Fails

• Authentication error: Run wrangler login to re-authenticate
• Missing binding: Check wrangler.json for correct binding configuration
• TypeScript errors: Run npm run build to identify issues

Runtime Errors

• AI binding not found: Ensure Workers AI is enabled on your account
• Browser binding not found: Enable Browser Rendering in your account
• Database not found: Check D1 database_id in wrangler.json
• KV not found: Check KV namespace id in wrangler.json
• R2 not found: Verify bucket names in wrangler.json

Local Development Issues

• AI doesn’t work locally: Use npm run dev -- --remote for Workers AI
• Browser doesn’t work locally: Use npm run dev -- --remote for Browser Rendering
• R2 public URLs don’t work: Use npm run dev -- --remote to test with real R2

Production Best Practices

Use Environment Variables

Store sensitive values as secrets, not in code:

wrangler secret put API_KEY

Set Rate Limits

Use Cloudflare’s Rate Limiting to prevent abuse:

Configure in the Cloudflare dashboard under Security.

Monitor Usage

Track Worker invocations and errors:

Workers & Pages → Your Worker → Metrics

Enable Analytics

Use Workers Analytics for detailed insights:

Available on Workers Paid plan

Next Steps

Explore Experiments

Browse all available experiments

Architecture Patterns

Learn common patterns used across experiments