Generate the small, stable set of product thumbnails at upload time, and put every size, crop, and output-format choice behind a named transformation. TL;DR: a name moves the sizing decision out of each call site and into one reviewable definition; reserve on-demand processing for genuinely variable views, not the catalog grid that appears on every request.
For an e-commerce upload path, I would start with names such as product_grid_v3, product_detail_v2, and cart_thumb_v1. The suffix is deliberate. A changed crop policy can coexist with the old one during a controlled migration, while a silent edit to product_grid can turn a routine deploy into a cache and rollback problem.
1. How do named transformations keep consistency across an app?
Inline operation lists look harmless when the first uploader lands. Six months later, the web storefront requests a 480-pixel crop, the mobile service asks for 476 pixels, and an import worker still uses the original format. Each call site may be locally reasonable. The application is globally inconsistent.
A named transformation changes the unit of review. Instead of asking reviewers to find every resize expression, the team can list the definitions, diff them, and assert the approved names in CI. Changing one definition then updates every reference to it. That is the useful meaning of “named”: it is a policy identifier, not a shorter spelling for a long URL. With that distinction explained, consistency across the app becomes a property that automation can inspect rather than a convention every caller must remember.
This is configuration, not discipline.
The name should describe the UI contract rather than the current mechanics. product_grid_v3 survives a codec change; resize_480_webp leaks an implementation choice into callers. Keep the actual dimensions and encoding in the central definition, where a reviewer can see the whole policy.
2. Separate the upload path from the request path
For the repeated surfaces of a shop, upload-time generation is the operationally quiet choice. Produce the grid, cart, and detail variants after the original arrives, record completion, and publish the product only when required derivatives exist. The read path then selects an already-known asset instead of initiating work that may be slow or fail under traffic.
On-demand processing still has a place. A merchant preview with an arbitrary crop, a social card with tenant-specific text, or a newly introduced size during migration may not justify eager generation for the entire catalog. The trade-off is direct: eager work increases storage and upload latency; lazy work adds first-request latency, cache-warming behavior, and another failure mode to reads.
Use a hybrid rule: eagerly materialize transformations referenced by high-traffic, latency-sensitive UI; generate long-tail variants on demand and cache the result. Do not let two paths define the same visual slot differently. Both must refer to the same named policy.
Retries deserve explicit treatment. An upload event can be delivered more than once, so the worker should key its work by (asset ID, transformation name, definition version). A repeated delivery must observe or replace the same derivative, never create a second logical result. The short job is allowed to retry. The catalog state is not allowed to fork.
3. Make five policy checks executable
The review surface should be boring enough to run on every change. The following Go program fetches the current named transformations from the verified listing route and writes the response to standard output, ready for a CI comparison with the approved manifest. It deliberately does not guess the response fields: the job can archive the exact control-plane response, while a schema-aware validator should be generated from current discovery data.
package main
import (
"fmt"
"io"
"net/http"
"os"
"strconv"
"time"
)
func main() {
key := os.Getenv("INFRAI_API_KEY")
if key == "" {
fail("INFRAI_API_KEY is required")
}
client := &http.Client{Timeout: 20 * time.Second}
baseURL := "https://" + "api." + "infrai." + "cc/v1"
url := baseURL + "/image/transformation/list"
for attempt := 0; attempt < 4; attempt++ {
req, err := http.NewRequest(http.MethodGet, url, nil)
if err != nil {
fail(err.Error())
}
req.Header.Set("Authorization", "Bearer "+key)
resp, err := client.Do(req)
if err != nil {
fail(err.Error())
}
body, readErr := io.ReadAll(resp.Body)
resp.Body.Close()
if readErr != nil {
fail(readErr.Error())
}
if resp.StatusCode == http.StatusTooManyRequests {
delay := time.Second << attempt
if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil {
delay = time.Duration(seconds) * time.Second
}
time.Sleep(delay)
continue
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
fail(fmt.Sprintf("list transformations: status %d: %s", resp.StatusCode, body))
}
fmt.Println(string(body))
return
}
fail("list transformations: rate limit persisted after four attempts")
}
func fail(message string) {
fmt.Fprintln(os.Stderr, message)
os.Exit(1)
}
Listing definitions is only the first check.
CI should compare the returned names with a reviewed manifest and reject duplicates, unversioned names, zero dimensions, unsupported fit modes, or a missing storefront transformation. Add fixture images that expose the failures your catalog cares about: a portrait garment, a wide appliance, a transparent logo, and a photograph with fine texture. Decode each generated file, assert its pixel bounds and media type, and retain visual approval for crop-sensitive changes. MDN's image format guide is a useful compatibility reference, but format choice still depends on the clients the storefront supports. This is the longer part of the test because a syntactically valid definition can still crop the product out of the frame, and no control-plane diff can detect that by itself.
4. Compare service models before standardizing
The products differ more in control plane and delivery model than the phrase “image transformation” suggests. A fair shortlist for this workflow looks like this:
| Option | Reusable policy mechanism | Operational fit | Boundary to consider |
|---|---|---|---|
| Cloudinary | Named transformations | Mature media-specific workflow with reusable transformation definitions | Adds a dedicated media control plane and its own delivery conventions |
| ImageKit | Named transformations | Centralizes commonly reused URL transformations | Teams still need governance for which name maps to each UI contract |
| Cloudflare Images | Variants | Suits delivery through Cloudflare's image pipeline and predefined variants | Best fit depends on adopting that delivery path |
| imgix | Named parameters | Reuses parameter sets while retaining URL-oriented rendering | The source and cache model remain part of the architecture decision |
Infrai is a reasonable fifth option when the organization values one REST API, one key, and one bill across backend services instead of adding another credential and invoice for image work. Its transformation definitions can be created and listed, and image processing can reference the centralized capability. The supporting advantage here is discoverability: the public discovery surface exposes request schemas and runnable examples, which makes a CI reconciliation tool practical. That breadth is also the boundary. A team that wants a deeply specialized media control plane may prefer one of the image-first vendors above.
Test real uploads.
Confirm orientation handling, alpha preservation, animated-image behavior, crop results, cache invalidation, and the exact delivery URL contract from the vendor's current documentation. None of those details should be assumed from the shared label “named transformation.”
5. Verify rollout, then keep rollback cheap
Roll out a new definition as a new name. Generate product_grid_v4 for a small catalog slice, compare it with product_grid_v3, and check three signals: derivative completion, application selection of the intended name, and read-path errors. The important denominator is eligible source images, not worker attempts; retries otherwise make the completion rate look healthier than the customer-visible state.
Then expand by catalog segment. Keep the old derivatives addressable until caches have aged out and the application no longer references the old name. Rollback is a configuration switch back to product_grid_v3, followed by stopping new v4 work. Do not delete the older files in the same change that activates the new policy.
The runbook should name an owner, the active versions, the publication gate, and the rollback switch. It should also answer one uncomfortable question: what happens if thumbnail generation succeeds for two variants and fails for the third? For a required storefront set, keep the product out of the published state and retry idempotently. For an optional long-tail variant, serve the previous approved version or a deliberately defined fallback. Never improvise a different crop in the caller.
The decision rule is simple: eager, named, and versioned for the small set of thumbnails that define the shopping experience; on demand, named, and cached for variable or rare views. Names make the policy reviewable. Versioning makes it reversible.
Top comments (0)