jekcms converts every uploaded image to AVIF (quality 60) and WebP (quality 82), creates four sizes and prints a picture tag that lets the browser pick the right format. Here is what happens at upload time, step by step.
Why There Is a Separate Media Pipeline
Authors often upload photos straight from their phones. A 4000x3000 JPEG weighs several megabytes, and the same file ends up as a small sidebar image, a homepage card and a large cover on the post page. If the full-size file is sent everywhere, pages get heavier than they need to be.
That is why jekcms processes images at upload time. Before the file is written to disk it is checked, converted to modern formats and copied at several sizes.
What Happens at Upload
1. Check
The file is read to confirm it really is an image; a file named .jpg that is not an image is rejected. The default size limit is 50 MB and can be changed in the server configuration.
2. Format Conversion
The image is converted to AVIF as the primary format and WebP as the fallback. The default quality is 60 for AVIF and 82 for WebP. Both can be changed in the settings: AVIF between 40 and 80, WebP between 55 and 95. Once the conversion succeeds the original file is deleted; if the server has no GD library, the image stays in its original format.
Because the image is saved again, EXIF data from phone photos (location, device model, capture time) is not carried into the new file. Sharing a photo of your office does not share its location as well.
3. Size Copies
Four copies are created for every image:
- thumbnail: 400x400, cropped from the centre. For small cards and panel lists.
- medium: up to 800 pixels, aspect ratio kept. For post cards and archive pages.
- large: up to 1600 pixels, aspect ratio kept. For the content area on the post page.
- pinterest: 1000x1500, cropped to 2:3 from the centre. Kept separately because vertical images look better on Pinterest.
This is how the table is defined in the core:
'thumbnail' => ['width' => 400, 'height' => 400, 'crop' => true],
'medium' => ['width' => 800, 'height' => 800, 'crop' => false],
'large' => ['width' => 1600, 'height' => 1600, 'crop' => false],
'pinterest' => ['width' => 1000, 'height' => 1500, 'crop' => true]4. Storage
Files are written to year and month folders, and the database stores the base path without an extension: images/2026/03/photo. The size suffix and format are added to that path when the page is built.
The Right Format on the Page
Themes print the featured image with the get_featured_picture() function. It produces a <picture> tag with the AVIF source first and the WebP source second, and the browser picks the first format it supports. Each source carries a srcset with several widths, so a small card on a phone does not download the large file.
Width and height are written on the image tag too. The browser can reserve the space before the image arrives, so content does not jump around while the page loads; the CLS value in Core Web Vitals measures exactly that.
A Common Path Mistake
The most common error on sites with manual imports is a doubled uploads/ path. If the database holds uploads/images/2026/03/photo and /uploads is added again when the address is built, the result is https://site.com/uploads/uploads/... and the image returns a 404. Paths in the database should always be relative to the uploads folder, without a leading uploads/.
// Right: database holds "images/2026/03/photo"
// Address: https://site.com/uploads/images/2026/03/photo.avif
// Wrong: database holds "uploads/images/2026/03/photo"
// Address: https://site.com/uploads/uploads/images/2026/03/photo.avif (404)What You Gain
Conversion and resizing make the server work at upload time, but that cost is paid once per image. The gain lasts as long as the image stays on the site: small copies on cards, a large copy in the post, and AVIF or WebP files that are much lighter than JPEG everywhere. How much smaller they get depends on the source photo.
