Image Handling: Downloads, Caching, and CDN

The problem: expiring image URLs

Most source platforms do not serve images from permanent URLs. Airtable is the most notable example — attachment URLs expire approximately 2 hours after they are generated. If you paste an Airtable image URL directly into Webflow, it works initially but breaks within hours, leaving your site with missing images.

Other platforms have similar limitations. Google Sheets cannot host images at all. Notion attachment URLs are signed and time-limited. Even platforms with stable URLs can change them without warning during infrastructure updates.

How Trellis solves this

Trellis treats every image as a file to be downloaded, cached, and re-hosted:

1. Download — during sync, Trellis downloads the full-resolution image from the source URL.
2. Cache — the image is stored in Firebase Storage, which provides a persistent, non-expiring URL.
3. Upload to Webflow — Trellis uploads the cached image to Webflow's asset CDN via the Data API.
4. Hash tracking — Trellis stores a content hash of each image. On subsequent syncs, images are only re-downloaded if the hash has changed, saving bandwidth and time.

The result: your Webflow site always shows working images, regardless of what happens to the original source URLs.

File size limits

Webflow imposes a 4 MB per image limit for CMS-uploaded assets. Trellis checks file sizes during sync and will:

• Upload images under 4 MB normally.
• Warn you about images that exceed the limit so you can resize them in your source.
• Skip oversized images rather than failing the entire sync — the rest of your content still syncs successfully.

If you regularly work with large images (high-resolution photography, print-quality assets), resize or compress them in your source before syncing.

Format handling

Trellis supports the image formats that Webflow accepts:

• JPEG — the most common format for photographs.
• PNG — used for graphics, logos, and images requiring transparency.
• WebP — modern format with better compression, supported by Webflow.
• GIF — supported for simple animations and legacy content.

SVG files are handled differently — Webflow treats them as code assets rather than CMS images. SVG support depends on the specific Webflow field type and plan.

Gallery images via companion collections

When a single source record has multiple images (a photo gallery, a product carousel, a property listing), Trellis uses companion collections to store them in Webflow.

How it works:

1. Each image becomes its own item in a companion collection (e.g., "Property Photos").
2. Each companion item has a reference field pointing back to the parent item (e.g., "Parent Property").
3. A sort order field controls the display sequence.
4. On the Webflow side, a nested Collection List displays the gallery filtered by the parent reference.

This pattern works around Webflow's single-image-per-field limitation while preserving full gallery functionality.

Further reading

• Image Gallery Field — field configuration for multi-image galleries.
• Companion Collections Explained — the architecture behind gallery collections.