Deployment Guide - Cloudflare Experiments

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:

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.

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.

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.

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.

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

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

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:

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"
  }
}

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.

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:

Add domain to Cloudflare

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

Navigate to Workers & Pages

In the Cloudflare dashboard:

Go to Workers & Pages
Select your deployed Worker
Click the Triggers tab

Add custom domain

Click Add Custom Domain
Enter your subdomain (e.g., api.example.com)
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
Wrangler CLI

Go to Workers & Pages
Select your Worker
Go to Settings → Variables
Add variables (Plain text or Secret)
Click Save

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

Verify local functionality

npm run dev
# Test all endpoints

Check TypeScript

npm run build
# or: tsc --noEmit

Create required resources

D1 databases
KV namespaces
R2 buckets
Set environment variables

Run migrations (if applicable)

npm run db:migrate

Deploy

npm run deploy

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

Resources

​Quick Deploy (Click-to-Deploy)

​Deployment URL Format

​Manual Deployment

​Custom Domains

​Environment Variables

​Deployment Checklist

​Troubleshooting

​Deployment Fails

​Runtime Errors

​Local Development Issues

​Production Best Practices

Use Environment Variables

Set Rate Limits

Monitor Usage

Enable Analytics

​Next Steps

Explore Experiments

Architecture Patterns

Quick Deploy (Click-to-Deploy)

Deployment URL Format

Manual Deployment

Custom Domains

Environment Variables

Deployment Checklist

Troubleshooting

Deployment Fails

Runtime Errors

Local Development Issues

Production Best Practices

Next Steps