Image resizing and compression

Images uploaded through the built-in File Manager are resized and re-encoded before they are stored. Both steps are on by default and are configured through the imageCompressionOptions object.

WARNING

Uploads handled by a custom file manager never reach this pipeline, so neither resizing nor compression is applied to them.

The pipeline runs with the built-in storage, with custom storage integrations (GCS, S3, R2, DigitalOcean Spaces), and with self-hosted storage.

INFO

Only PNG, GIF, and JPEG uploads are accepted, and the file type is checked by reading the file's leading bytes rather than its extension. WebP and SVG are rejected. GIF files skip resizing and compression entirely so their animation is preserved.

Automatic image resizing

Enabled by default, this feature resizes uploaded images based on your template's width.

The limit is twice the current template width, which keeps images sharp on high-resolution (Retina) displays. With the default 600px template that gives a maximum width of 1200px, and a template with a different body width scales accordingly. Height follows the image's original aspect ratio.

Resizing only ever shrinks an image. Anything already narrower than twice the template width keeps its original dimensions.

INFO

Disabling this feature means images retain their original dimensions, which could affect how they appear in your layout and increase file size.

How to disable auto-resizing:

imageCompressionOptions: {
    enableAutoResize: false,
},

Automatic image compression

Also enabled by default, this feature re-encodes images on upload to reduce file size:

• JPEG images are encoded at 95% quality
• PNG images are encoded at 80% quality

If re-encoding produces a file larger than the original, the original is kept.

How to disable compression entirely:

imageCompressionOptions: {
    enableCompression: false
},

How to set custom compression levels:

imageCompressionOptions: {
// `qualityJpeg` and `qualityPng` are quality values between 0 and 1.
    qualityJpeg: 0.5, // 50% quality
    qualityPng: 0.7, // 70% quality
},

WARNING

These are quality values, not compression amounts: a lower number means a smaller file and a more degraded image. Values outside the 0 to 1 range are passed through to the encoder unchanged, so keep them inside that range.