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/variants-guide.md

View on GitHub
# Variants Guide - Named vs Flexible

Complete guide to Cloudflare Images variants.

---

## What Are Variants?

Variants define how images should be resized and transformed for different use cases.

**Two Types**:
1. **Named Variants** - Predefined transformations (up to 100)
2. **Flexible Variants** - Dynamic transformations (unlimited)

---

## Named Variants

### Overview

Pre-configured transformations that apply consistently across all images.

**Limits**: 100 variants per account
**Use with**: Public and private images (signed URLs compatible)

### Creating Named Variants

**Via API**:
```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "thumbnail",
    "options": {
      "fit": "cover",
      "width": 300,
      "height": 300,
      "metadata": "none"
    },
    "neverRequireSignedURLs": false
  }'
```

**Via Dashboard**:
1. Dashboard → Images → Variants
2. Create variant
3. Set dimensions, fit mode, metadata handling

### Using Named Variants

**URL Format**:
```
https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>
```

**Example**:
```html
<img src="https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/abc123/thumbnail" />
```

### Common Named Variants

```javascript
const presets = {
  thumbnail: { width: 300, height: 300, fit: 'cover' },
  avatar: { width: 200, height: 200, fit: 'cover' },
  small: { width: 480, fit: 'scale-down' },
  medium: { width: 768, fit: 'scale-down' },
  large: { width: 1920, fit: 'scale-down' },
  hero: { width: 1920, height: 1080, fit: 'cover' },
  product: { width: 800, height: 800, fit: 'contain' }
};
```

### When to Use Named Variants

✅ **Use when**:
- Consistent sizes needed across app
- Private images (signed URLs required)
- Predictable, simple URLs
- Team collaboration (shared definitions)

❌ **Don't use when**:
- Need dynamic sizing per request
- Rapid prototyping with many sizes
- Approaching 100-variant limit

---

## Flexible Variants

### Overview

Dynamic transformations using params directly in URL.

**Limits**: Unlimited transformations
**Use with**: Public images only (signed URLs NOT compatible)

### Enabling Flexible Variants

**One-time setup per account**:
```bash
curl --request PATCH \
  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{"flexible_variants": true}'
```

### Using Flexible Variants

**URL Format**:
```
https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<TRANSFORMATION_PARAMS>
```

**Examples**:
```html
<!-- Basic resize -->
<img src="https://imagedelivery.net/HASH/ID/w=400,h=300" />

<!-- With quality and format -->
<img src="https://imagedelivery.net/HASH/ID/w=800,q=85,f=auto" />

<!-- Sharpen and crop -->
<img src="https://imagedelivery.net/HASH/ID/w=600,h=600,fit=cover,sharpen=3" />

<!-- Blur effect -->
<img src="https://imagedelivery.net/HASH/ID/w=500,blur=20,q=50" />
```

### Available Parameters

Same as transformation options:
- `w`, `h` - Width, height
- `fit` - Fit mode (scale-down, contain, cover, crop, pad)
- `q` - Quality (1-100)
- `f` - Format (auto, avif, webp, jpeg)
- `gravity` - Crop focal point (auto, face, left, right, top, bottom)
- `blur`, `sharpen`, `brightness`, `contrast`, `gamma`
- `rotate`, `flip`
- `dpr` - Device pixel ratio
- `metadata` - EXIF handling (none, copyright, keep)
- `anim` - Preserve animation (true/false)

### When to Use Flexible Variants

✅ **Use when**:
- Dynamic sizing needs
- Public images only
- Rapid prototyping
- User-controlled transformations

❌ **Don't use when**:
- Need signed URLs (private images)
- Want consistent, predictable URLs
- Team needs shared definitions

---

## Comparison Table

| Feature | Named Variants | Flexible Variants |
|---------|---------------|-------------------|
| **Limit** | 100 per account | Unlimited |
| **Signed URLs** | ✅ Compatible | ❌ Not compatible |
| **URL Format** | `/thumbnail` | `/w=400,h=300,fit=cover` |
| **URL Length** | Short, clean | Longer, dynamic |
| **Setup** | Create variants first | Enable once, use anywhere |
| **Use Case** | Consistent sizes | Dynamic sizing |
| **Team Sharing** | Shared definitions | Ad-hoc transformations |
| **Private Images** | ✅ Supported | ❌ Public only |

---

## Combining Both

You can use both types in the same account:

```html
<!-- Named variant for avatar (private image, signed URL) -->
<img src="https://imagedelivery.net/HASH/PRIVATE_ID/avatar?exp=123&sig=abc" />

<!-- Flexible variant for public thumbnail -->
<img src="https://imagedelivery.net/HASH/PUBLIC_ID/w=300,h=300,fit=cover" />
```

---

## Best Practices

### For Named Variants

1. **Create core sizes first**: thumbnail, small, medium, large
2. **Use descriptive names**: `product-square`, `hero-wide`, `avatar-round`
3. **Document variant usage**: Share definitions with team
4. **Set consistent quality**: 85 for photos, 90+ for graphics
5. **Use `metadata: none`**: Unless specific need to preserve EXIF

### For Flexible Variants

1. **Always use `f=auto`**: Optimal format for each browser
2. **Limit dynamic range**: Don't allow arbitrary sizes (performance)
3. **Cache popular sizes**: Create named variants for common sizes
4. **URL-encode params**: Especially if using special characters
5. **Public images only**: Remember signed URL incompatibility

---

## Migration Strategies

### From Flexible to Named

If approaching flexibility limits or need signed URLs:

```javascript
// Analyze usage logs
const popularSizes = analyzeImageRequests();
// { w=300,h=300: 50000, w=800,h=600: 30000, ... }

// Create named variants for top sizes
for (const [params, count] of Object.entries(popularSizes)) {
  if (count > 10000) {
    await createVariant(getNameForParams(params), parseParams(params));
  }
}

// Update URLs from flexible to named
// Before: /w=300,h=300,fit=cover
// After: /thumbnail
```

### From Named to Flexible

If need more than 100 variants:

1. Enable flexible variants
2. Gradually migrate to dynamic params
3. Keep popular sizes as named variants
4. Use flexible for long-tail sizes

---

## Cost Considerations

**Named Variants**:
- Cached at edge (fast delivery)
- Predictable bandwidth
- Good for high traffic

**Flexible Variants**:
- Also cached at edge
- More cache keys (potentially)
- Good for diverse sizing needs

**Both**: First transformation billable, subsequent cached requests free

---

## Official Documentation

- **Create Variants**: https://developers.cloudflare.com/images/manage-images/create-variants/
- **Enable Flexible Variants**: https://developers.cloudflare.com/images/manage-images/enable-flexible-variants/
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