---
name: tigris-image-optimization
description: Use when resizing images, generating thumbnails, serving responsive images, or optimizing image delivery with Tigris — covers Next.js, Remix, Rails, Django, Laravel, Express
---

# Tigris Image Optimization

Resize, crop, and optimize images stored in Tigris. Generate thumbnails on upload, serve responsive images, and leverage Tigris's global CDN for fast delivery.

## Strategy Overview

| Approach | When to Use | Pros | Cons |
|----------|------------|------|------|
| Process on upload | Thumbnails, fixed sizes | Fast serving, predictable | Storage cost per variant |
| Process on request | Many size variations | Flexible, less storage | Latency on first request |
| Client-side resize | Before upload | Saves bandwidth, fast upload | Less control over quality |

**Recommended:** Process on upload for known sizes (avatar, thumbnail, cover). Use public buckets for CDN delivery — Tigris serves public files from the nearest global edge automatically.

---

## Upload-Time Processing (General Pattern)

Generate variants when a file is uploaded, store each variant as a separate object:

```
avatars/user-123.jpg          # original
avatars/user-123-thumb.jpg    # 100x100
avatars/user-123-medium.jpg   # 400x400
avatars/user-123-large.jpg    # 800x800
```

Use `access: "public"` for images that need fast, CDN-backed delivery.

---

## Framework Guides

Read the resource file for your framework:

- **Next.js** — Read `./resources/nextjs.md` for next/image config and Sharp processing
- **Remix** — Read `./resources/remix.md` for Sharp in action functions and responsive srcset
- **Express** — Read `./resources/express.md` for Sharp middleware with Multer
- **Rails** — Read `./resources/rails.md` for Active Storage variants
- **Django** — Read `./resources/django.md` for django-imagekit and Pillow processing
- **Laravel** — Read `./resources/laravel.md` for Intervention Image

---

## CDN Delivery

Tigris public buckets serve files from the nearest global edge — no separate CDN setup needed.

**Cache headers for images:**

```typescript
await put("images/hero.jpg", buffer, {
  access: "public",
  contentType: "image/jpeg",
});
```

For immutable content-hashed filenames (e.g., `hero-abc123.jpg`), use long cache times. For mutable paths, use shorter TTLs or ETags.

---

## Critical Rules

**Always:** Use `access: "public"` for images served to users (enables CDN) | Generate thumbnails at upload time for known sizes | Use WebP/AVIF for smaller file sizes | Set explicit `contentType`

**Never:** Process images on every request without caching | Store only originals if you always serve thumbnails | Resize in the browser after downloading full-size images

---

## Related Skills

- **tigris-file-uploads** — Full upload patterns per framework
- **tigris-egress-optimizer** — Reduce bandwidth costs from image serving

## Official Documentation

- Tigris SDK: https://www.tigrisdata.com/docs/sdks/tigris/
- Sharp: https://sharp.pixelplumbing.com/