Skip to content

secondsky/claude-skills / plugins/cloudflare-images/skills/cloudflare-images

cloudflare-images

Unverified

This skill should be used when the user asks to "upload images to Cloudflare", "implement direct creator upload", "configure image transformations", "optimize WebP/AVIF", "create image variants", "generate signed URLs", "add image watermarks", "integrate with Next.js/Remix", "configure webhooks", "debug CORS errors", "troubleshoot error 5408/9401-9413", or "build responsive images with Cloudflare Images API".

FileKindSize
SKILL.mdskill md13.9 KB
assets/diagrams/direct-upload-workflow.mdmarkdown5.0 KB
assets/diagrams/transformation-pipeline.mdmarkdown8.2 KB
assets/diagrams/variants-structure.mdmarkdown10.6 KB
examples/basic-upload/.env.exampleother474 B
examples/basic-upload/README.mdmarkdown6.5 KB
examples/basic-upload/package.jsonmanifest542 B
examples/basic-upload/public/index.htmlother12.7 KB
examples/basic-upload/src/index.tsscript2.7 KB
examples/basic-upload/wrangler.jsoncother378 B
examples/private-images/.env.exampleother631 B
examples/private-images/README.mdmarkdown12.5 KB
examples/private-images/package.jsonmanifest741 B
examples/private-images/public/index.htmlother18.0 KB
examples/private-images/src/index.tsscript5.2 KB
examples/private-images/wrangler.jsoncother427 B
examples/responsive-gallery/README.mdmarkdown4.3 KB
references/api-reference.mdmarkdown8.1 KB
references/content-credentials.mdmarkdown11.6 KB
references/custom-domains.mdmarkdown10.5 KB
references/direct-upload-complete-workflow.mdmarkdown11.2 KB
references/format-optimization.mdmarkdown7.2 KB
references/framework-integration.mdmarkdown15.4 KB
references/overlays-watermarks.mdmarkdown11.1 KB
references/polish-compression.mdmarkdown10.4 KB
references/responsive-images-patterns.mdmarkdown6.1 KB
references/setup-guide.mdmarkdown3.8 KB
references/signed-urls-guide.mdmarkdown7.5 KB
references/sourcing-kit.mdmarkdown15.0 KB
references/top-errors.mdmarkdown11.7 KB
references/transformation-options.mdmarkdown6.4 KB
references/variants-guide.mdmarkdown6.7 KB
references/webhooks-guide.mdmarkdown11.8 KB
scripts/analyze-usage.shexecutablescript6.6 KB
scripts/check-versions.shexecutablescript3.3 KB
scripts/generate-signed-url.shexecutablescript4.4 KB
scripts/test-upload.shexecutablescript4.4 KB
scripts/validate-variants.shexecutablescript5.2 KB
templates/batch-upload.tsscript7.8 KB
templates/direct-creator-upload-backend.tsscript5.4 KB
templates/direct-creator-upload-frontend.htmlother8.4 KB
templates/nextjs-integration.tsxother11.4 KB
templates/overlay-watermark.tsscript13.7 KB
templates/package.jsonmanifest387 B
templates/remix-integration.tsxother15.0 KB
templates/responsive-images-srcset.htmlother8.0 KB
templates/signed-urls-generation.tsscript6.6 KB
templates/transform-via-url.tsscript6.5 KB
templates/transform-via-workers.tsscript8.7 KB
templates/upload-api-basic.tsscript3.8 KB
templates/upload-via-url.tsscript4.9 KB
templates/variants-management.tsscript7.0 KB
templates/webhook-handler.tsscript8.8 KB
templates/wrangler-images-binding.jsoncother1.2 KB

references/format-optimization.md

View on GitHub
# Format Optimization

Complete guide to automatic WebP/AVIF conversion and format selection.

---

## format=auto (Recommended)

Automatically serve optimal format based on browser support.

**Priority**:
1. **AVIF** - Best compression (Chrome, Edge)
2. **WebP** - Good compression (Safari, Firefox)
3. **Original format** - Fallback (older browsers)

**Usage**:
```typescript
// URL format
/cdn-cgi/image/width=800,quality=85,format=auto/image.jpg

// Workers format
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      quality: 85,
      format: 'auto'
    }
  }
});

// Cloudflare Images
https://imagedelivery.net/HASH/ID/w=800,q=85,f=auto
```

---

## Browser Support Detection

Cloudflare automatically checks the `Accept` header.

**Chrome/Edge**:
```
Accept: image/avif,image/webp,image/apng,image/*,*/*
```
→ Serves AVIF

**Safari**:
```
Accept: image/webp,image/apng,image/*,*/*
```
→ Serves WebP

**Older browsers**:
```
Accept: image/jpeg,image/png,image/*,*/*
```
→ Serves original format (JPEG)

---

## Manual Format Selection

### In URL Transformations

```html
<!-- AVIF (best compression) -->
<img src="/cdn-cgi/image/format=avif/image.jpg" />

<!-- WebP (good compression, wide support) -->
<img src="/cdn-cgi/image/format=webp/image.jpg" />

<!-- JPEG (progressive) -->
<img src="/cdn-cgi/image/format=jpeg/image.jpg" />

<!-- Baseline JPEG (older devices) -->
<img src="/cdn-cgi/image/format=baseline-jpeg/image.jpg" />
```

### In Workers

```typescript
// Get optimal format from Accept header
function getOptimalFormat(request: Request): 'avif' | 'webp' | 'auto' {
  const accept = request.headers.get('accept') || '';

  if (/image\/avif/.test(accept)) {
    return 'avif';
  } else if (/image\/webp/.test(accept)) {
    return 'webp';
  }

  return 'auto'; // Cloudflare decides
}

return fetch(imageURL, {
  cf: {
    image: {
      format: getOptimalFormat(request)
    }
  }
});
```

---

## Format Comparison

| Format | Compression | Quality | Support | Use Case |
|--------|-------------|---------|---------|----------|
| **AVIF** | Best (~50% smaller) | Excellent | Modern browsers | First choice (auto) |
| **WebP** | Good (~30% smaller) | Excellent | Wide support | Fallback from AVIF |
| **JPEG** | Standard | Good | Universal | Fallback, photos |
| **PNG** | Lossless | Lossless | Universal | Graphics, transparency |

**File Size Example** (1920x1080 photo):
- Original JPEG: 500 KB
- WebP: ~350 KB (30% smaller)
- AVIF: ~250 KB (50% smaller)

---

## Progressive vs Baseline JPEG

**Progressive JPEG** (default):
- Loads in multiple passes (low→high quality)
- Better for slow connections
- Slightly larger file size

**Baseline JPEG**:
- Loads top-to-bottom
- Better for older devices
- Slightly smaller file size

**Usage**:
```
format=jpeg → Progressive JPEG
format=baseline-jpeg → Baseline JPEG
```

---

## WebP Compression Modes

```typescript
// Fast compression (faster encoding, larger file)
fetch(imageURL, {
  cf: {
    image: {
      format: 'webp',
      compression: 'fast'
    }
  }
});

// Lossless WebP (no quality loss, larger file)
fetch(imageURL, {
  cf: {
    image: {
      format: 'webp',
      compression: 'lossless'
    }
  }
});
```

---

## Responsive Images with format=auto

```html
<picture>
  <!-- Explicit AVIF for modern browsers -->
  <source
    type="image/avif"
    srcset="
      https://imagedelivery.net/HASH/ID/w=480,f=avif 480w,
      https://imagedelivery.net/HASH/ID/w=1920,f=avif 1920w
    "
  />

  <!-- WebP fallback -->
  <source
    type="image/webp"
    srcset="
      https://imagedelivery.net/HASH/ID/w=480,f=webp 480w,
      https://imagedelivery.net/HASH/ID/w=1920,f=webp 1920w
    "
  />

  <!-- JPEG fallback -->
  <img
    srcset="
      https://imagedelivery.net/HASH/ID/w=480,f=jpeg 480w,
      https://imagedelivery.net/HASH/ID/w=1920,f=jpeg 1920w
    "
    src="https://imagedelivery.net/HASH/ID/w=1920,f=jpeg"
    alt="Responsive image with format fallbacks"
  />
</picture>

<!-- OR: Let format=auto handle it -->
<img
  srcset="
    https://imagedelivery.net/HASH/ID/w=480,f=auto 480w,
    https://imagedelivery.net/HASH/ID/w=1920,f=auto 1920w
  "
  src="https://imagedelivery.net/HASH/ID/w=1920,f=auto"
  alt="Auto-format responsive image"
/>
```

---

## Quality Recommendations by Format

```typescript
const qualitySettings = {
  jpeg: 85,        // Standard for photos
  webp: 85,        // Same as JPEG
  avif: 85,        // AVIF efficient at same quality
  png: undefined,  // Lossless (quality N/A)
  graphics: 95     // High quality for logos/text
};

// Photos
/cdn-cgi/image/width=800,quality=85,format=auto/photo.jpg

// Graphics with text
/cdn-cgi/image/width=800,quality=95,format=auto/logo.png

// Thumbnails (lower quality acceptable)
/cdn-cgi/image/width=300,quality=75,format=auto/thumb.jpg
```

---

## Animation Support

**GIF**:
```
format=auto → Still GIF or first frame
anim=true → Preserve animation
```

**Animated WebP**:
```typescript
fetch(animatedGif, {
  cf: {
    image: {
      format: 'webp',
      anim: true // Preserve animation
    }
  }
});
```

---

## Metadata Handling

**Strip metadata** (smaller file size):
```
metadata=none
```

**Keep copyright** (default for JPEG):
```
metadata=copyright
```

**Keep all EXIF** (GPS, camera settings):
```
metadata=keep
```

**Example**:
```
/cdn-cgi/image/width=800,format=auto,metadata=none/photo.jpg
```

---

## Cost Optimization

1. **Use format=auto**: Smallest files = less bandwidth
2. **Reasonable quality**: 80-85 for photos, 90-95 for graphics
3. **Strip metadata**: `metadata=none` for public images
4. **Cache at edge**: First transformation billable, subsequent free
5. **WebP animations**: Convert GIF to animated WebP (smaller)

---

## Testing Format Support

```html
<script>
// Check AVIF support
const avifSupport = document.createElement('canvas')
  .toDataURL('image/avif').indexOf('data:image/avif') === 0;

// Check WebP support
const webpSupport = document.createElement('canvas')
  .toDataURL('image/webp').indexOf('data:image/webp') === 0;

console.log('AVIF:', avifSupport); // true in Chrome/Edge
console.log('WebP:', webpSupport); // true in modern browsers
</script>
```

**But**: Let Cloudflare handle this with `format=auto`!

---

## Common Patterns

### Hero Image
```
width=1920,height=1080,fit=cover,quality=85,format=auto,metadata=none
```

### Thumbnail
```
width=300,height=300,fit=cover,quality=75,format=auto,metadata=none
```

### Avatar
```
width=200,height=200,fit=cover,gravity=face,quality=90,format=auto
```

### Product Photo
```
width=800,height=800,fit=contain,quality=90,sharpen=2,format=auto
```

### Blur Placeholder (LQIP)
```
width=50,quality=10,blur=20,format=webp,metadata=none
```

---

## Best Practices

1. **Always use format=auto**: Let Cloudflare optimize
2. **Quality 80-90**: Balance file size and quality
3. **Strip unnecessary metadata**: Smaller files
4. **Test on real devices**: Verify format delivery
5. **Monitor bandwidth**: Check Cloudflare Analytics
6. **Use WebP for animations**: Smaller than GIF
7. **Progressive JPEG for photos**: Better perceived load time

---

## Official Documentation

- **Transform via URL**: https://developers.cloudflare.com/images/transform-images/transform-via-url/
- **Supported Formats**: https://developers.cloudflare.com/images/transform-images/#supported-formats-and-limitations
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall