How to set up automated image optimization in Contentful

If you’re running a site or app that pulls images from a CMS, you know that unoptimized images slow everything down. Bloated pages, annoyed users, unhappy search rankings—the works. If you’re using Contentful and want to automate image optimization (instead of uploading 20 versions of every asset), this guide’s for you.

Let’s skip the buzzwords and get to what actually works—and how to avoid common traps.

Why bother with automated image optimization?

Here’s the reality: images are usually the biggest files on your pages. If you just dump them into your CMS and call it a day, you’re making your site heavier than it needs to be. Automated optimization means:

  • Smaller files, faster loads. No one’s waiting around for your 4MB hero image.
  • Better user experience. Especially important for mobile and slow connections.
  • You don’t have to babysit uploads. Let automation handle resizing, format conversion, and compression.

Contentful actually makes this pretty doable, but you’ll need to set things up right. There are built-in options, plus ways to go further if you need to.

Step 1: Understand Contentful’s Image API (and its limits)

First things first: Contentful doesn't optimize images at upload. Instead, it gives you an Image API you can use to resize, crop, and compress images on the fly as you request them. This means:

  • You can change image size, quality, and even formats (like WebP) just by tweaking the image URL.
  • Your original images stay untouched in Contentful. Optimizations only happen when images are served.
  • You’re responsible for requesting the right versions for your front end.

What works:
- It’s easy to implement if you control the frontend. - No need for third-party plugins or extra build steps.

What doesn’t:
- If you want to optimize images at upload (e.g., for storage savings), you’ll need custom automation or external services. - If you’re using Contentful’s images in third-party apps or emails, optimization is limited.

Step 2: Figure out your image needs

Before you start hacking URLs, get clear on what your site or app actually needs. Don’t over-engineer.

  • List your image use cases: Hero banners, thumbnails, avatars, galleries, etc.
  • Decide on sizes: Figure out the max width/height you need for each.
  • Pick formats: JPEG for photos, PNG for graphics, maybe WebP for modern browsers.
  • Think about retina displays: You may want 2x or 3x sizes for sharpness.

Pro tip:
Don’t try to serve one-size-fits-all images. A 2000px-wide hero image shrunk down to 80px for a thumbnail is just wasted bandwidth.

Step 3: Use Contentful’s Image API to serve optimized images

This is where the magic (and the URL hacking) happens.

Contentful image URLs look like this:

https://images.ctfassets.net/{space_id}/{asset_id}/{filename}

You tack on query strings to optimize. Here are the most useful parameters:

  • w and h: Set width and/or height in pixels (?w=600&h=400)
  • fit: Control cropping (fit=thumb, fit=fill, etc.)
  • fm: Format (fm=webp, fm=jpg, etc.)
  • q: Quality (1-100; lower = smaller file, e.g. q=75)

Example:
Serve a 400x300 WebP image at 70% quality:

https://images.ctfassets.net/your-space-id/your-asset-id/your-image.jpg?w=400&h=300&fm=webp&q=70

What works:
- You get a lot of control, all from the URL. - Works great with modern frontend frameworks—just build the URLs based on your needs.

Watch out for:
- If you forget these parameters, you’ll serve the full original image (not optimized!). - You can’t set defaults in Contentful—your app has to handle this.

Step 4: Automate image URL building in your code

Unless you love typing URLs by hand, automate this. Here’s how you can do it, depending on your stack:

JavaScript/React Example

js function getOptimizedImage(url, { width, height, format = "webp", quality = 75 }) { const params = new URLSearchParams(); if (width) params.append('w', width); if (height) params.append('h', height); if (format) params.append('fm', format); if (quality) params.append('q', quality); return ${url}?${params.toString()}; }

// Usage: const imgUrl = getOptimizedImage( "https://images.ctfassets.net/space/asset/photo.jpg", { width: 600, height: 400, format: "webp", quality: 70 } );

Static Site Generators

Many SSGs (like Gatsby, Next.js, or Eleventy) have plugins or utilities to help. For example:

  • Gatsby: gatsby-source-contentful + gatsby-plugin-image
  • Next.js: Use the next/image component and a custom loader for Contentful images.

Pro tip:
Don’t reinvent the wheel—use a plugin if your framework has a good one. But double-check that it actually builds the optimized URLs, not just the originals.

Step 5: Handle responsive images (srcset and sizes)

If you want images to look sharp on all devices and load as little data as possible, use the srcset and sizes attributes on <img> tags.

Example:

html Descriptive alt text

  • Browsers will pick the best image size for the device.
  • You can automate generating these URLs in your code.

What works:
- Huge savings for mobile users. - Images look crisp on retina screens.

What to ignore:
- Don’t bother generating a dozen breakpoints for a tiny icon. Use this for images where size matters.

Step 6: Advanced options (if you need them)

If Contentful’s Image API doesn’t cut it—or you have specific needs—you’ve got a few options:

a) Use an external image CDN (like Imgix, Cloudinary, or ImageKit)

  • These services can pull from Contentful assets, then offer more processing (like background removal, watermarking, etc.)
  • More expensive and more setup, but sometimes worth it for big sites or advanced needs.

b) Automate optimization at upload (not just on delivery)

  • You can build Contentful “apps” or use webhooks to process images after upload.
  • For example, trigger an AWS Lambda function to compress or resize images before they hit Contentful storage.
  • Not out-of-the-box—and honestly, most people don’t need this unless storage costs are huge or you have strict requirements.

Honest take:
For 99% of sites, Contentful’s built-in Image API is enough. Don’t overcomplicate unless you’ve actually hit a real limitation.

Step 7: Test your images—don’t just trust it's working

Once you’ve set up automated optimization, check your results with real tools:

  • Lighthouse (in Chrome DevTools) — Run a performance report and look for “Properly sized images.”
  • WebPageTest — See how your page loads for real users.
  • Network tab: Open your page in Chrome, inspect your images, and check file sizes and URLs.

If you see a 2MB image on mobile, something’s wrong. Fix those URL parameters or your image generation logic.

Step 8: Watch out for common gotchas

Some traps to avoid:

  • Serving only WebP: Not all browsers support it (looking at you, older Safari and IE). Offer JPEG or PNG fallback if needed.
  • Forgetting image alt text: Optimization is about speed and accessibility.
  • Blindly compressing everything: Over-compressed images look terrible. Find a balance—70–80% quality is usually good.

Quick Recap

  • Use Contentful’s Image API by tweaking image URLs—don’t settle for originals.
  • Automate URL generation in your code.
  • Use srcset and sizes for responsive images.
  • Test your results—don’t just assume it’s working.
  • Don’t overcomplicate unless you have a real reason.

Keep it simple. Iterate as you go.

Automated image optimization in Contentful isn’t rocket science, but it’s easy to miss details or overcomplicate things. Start small: optimize your most important images, automate what you can, and keep an eye on your site’s performance. You’ll save yourself headaches—and your users will thank you.

If something feels fiddly or fragile, it probably is. Simplify and move on.