Steps
Steps snap requested dimensions and quality values to a predefined set of allowed values. This reduces the number of unique cache keys, so similar requests share the same cached variant instead of generating near-identical images.
How it works
When a request includes w, h, or quality parameters, each value is rounded up to the nearest step before the image is processed or looked up in cache.
?w=500 → snaps to w=720
?w=1000 → snaps to w=1080
?quality=75 → snaps to quality=80Step arrays
Two separate step arrays control snapping for size and quality:
| Variable | Applies to | Default |
|---|---|---|
STEPS_SIZE | w and h parameters | [320, 480, 720, 1080, 1920, 2560, 3840] |
STEPS_QUALITY | quality parameter | [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] |
Configuration
Set custom step arrays in wrangler.jsonc as JSON-encoded strings:
"vars": {
"STEPS_SIZE": "[320, 640, 1280, 2560]",
"STEPS_QUALITY": "[25, 50, 75, 100]"
}Edge cases
| Scenario | Behavior |
|---|---|
| Value exceeds all steps | The largest step is used (e.g. w=5000 snaps to 3840) |
| No steps configured | Values pass through unchanged, no snapping is applied |
| No parameter provided | Steps have no effect; the image is served at its original dimensions/quality |
Why use steps?
Without steps, requests for w=799, w=800, and w=801 would each produce and cache a separate image. With the default size steps, all three snap to w=1080 and share a single cached variant - reducing storage usage and improving cache hit rates.