Developer Media Tools

Author: Developer Media Desk

  • How to deliver a hero image without hurting LCP

    How to deliver a hero image without hurting LCP

    Make the likely largest image easy to discover and quick to render.

    Find the actual LCP element

    First measure the page. The largest contentful paint element may be text on one viewport and an image on another. If the hero image is the LCP element, place its URL in discoverable HTML and avoid hiding it behind a late JavaScript fetch or CSS background when a normal image works.

    Give it the right priority

    Supply a properly sized responsive source, intrinsic dimensions, and an appropriate fetch priority where supported. Do not lazy-load an image that appears immediately in the viewport. Compressing the image helps only one part of LCP; render delay and late discovery can dominate.

    Check under realistic conditions

    Measure cold-cache mobile loading and inspect the network waterfall. Compare transfer size, request start, decode, and final render. A faster local Wi-Fi screenshot does not prove an improvement for a user on a slower connection.

    A concrete acceptance test

    Measure a cold mobile load and identify the actual LCP element. Change only the hero delivery rule, then compare request start time, transferred bytes, and render delay. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

    Implementation check

    • Measure the real LCP element at each viewport.
    • Make the hero URL discoverable in HTML.
    • Compare request start and render delay after the change.

    Related guides

    Primary reference: Official documentation.

  • Focal points and aspect ratios in automated cropping

    Focal points and aspect ratios in automated cropping

    Keep the subject in frame across cards, heroes, and mobile layouts.

    Save intent with the asset

    A center crop is convenient until a face, product, or text sits near an edge. Store an optional focal point as normalized coordinates on the source asset. A transformation can then center the requested crop around that point while clamping to the image bounds.

    Separate display and derivative decisions

    CSS object-position is useful when the browser displays an image in a fixed box, while server-side cropping saves bytes and ensures a consistent composition in shared previews. The same focal point can inform both, but test each target ratio: a very narrow banner may still need a manually approved crop.

    Give editors an escape hatch

    Automatic focal detection is a suggestion, not an editorial guarantee. Preview the common placements together and allow an override per important slot. Keep the original intact so a changed layout does not require re-uploading the image.

    A concrete acceptance test

    Preview a portrait subject in square, wide, and narrow slots. Move the focal point once and confirm all three placements update without changing the preserved source image. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

    Implementation check

    • Store focal coordinates with the original asset.
    • Preview square, landscape, and narrow slots.
    • Allow a manual crop override for important placements.

    Related guides

    Primary reference: Official documentation.

  • AVIF, WebP, or JPEG: choose formats by asset

    AVIF, WebP, or JPEG: choose formats by asset

    A format decision based on content, compatibility, and operational cost.

    Start with the content

    Photographs usually tolerate lossy compression; diagrams and interface screenshots expose ringing around sharp edges. WebP and AVIF can reduce transfer size, but visual quality, encoding time, and decode behavior matter. Keep a widely supported fallback when the audience includes older clients or embedded browsers.

    Measure at equal visual quality

    Compare outputs at the same displayed dimensions and similar perceived quality, not at the same numerical quality setting. Include transparency, animation, color profile, and metadata needs. Save a small representative corpus of photos, text-heavy screenshots, and graphics for repeatable tests.

    Negotiate without multiplying chaos

    A picture element or a well-defined CDN content negotiation strategy can serve modern formats and a fallback. Ensure the CDN cache key distinguishes format variants. Do not allow arbitrary format and quality combinations to create an unbounded derivative library.

    A concrete acceptance test

    Encode one photo, one UI screenshot, and one transparent graphic in each candidate format. Compare the downloaded bytes and visible edges at the exact size users will see. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

    Implementation check

    • Compare formats at matched visual quality.
    • Include text-heavy screenshots and transparent graphics in tests.
    • Cache each negotiated format under a distinct key.

    Related guides

    Primary reference: Official documentation.

  • Signed media URLs: access control at delivery time

    Signed media URLs: access control at delivery time

    Use expiring delivery links without making private assets public.

    Decide what is private

    Private originals, paid downloads, and temporary review files need a delivery authorization step. The application checks the viewer’s rights and issues a short-lived URL for the exact object or transformation. The URL is a bearer capability: anyone holding it can use it until it expires.

    Keep caches aligned with permissions

    Choose an expiration long enough for a download but short enough for the access policy. If authorization can be revoked instantly, a plain presigned URL may not meet the requirement. A CDN token, proxy, or session-bound approach may be needed, with explicit cache-key and purge behavior.

    Do not log the secret link

    Avoid putting signed query strings in analytics, error reports, or third-party referrers. Test clock skew and range requests for large video files. Make the application able to refresh a link without asking users to restart an otherwise valid download.

    A concrete acceptance test

    Open a private URL before authorization, during its valid window, and after expiry. Repeat with a byte-range request and inspect logs to ensure the signed query string was not captured. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

    Implementation check

    • Authorize the exact asset before signing a delivery URL.
    • Test expiration and byte-range requests.
    • Remove signed query strings from routine telemetry.

    Related guides

    Primary reference: Official documentation.

    Related field note

    Continue with A decision matrix for delivery URL signing.

  • When to use resumable uploads for media

    When to use resumable uploads for media

    Decide when a one-request upload is enough and when recovery matters.

    Match the protocol to the file

    For small images on stable connections, a direct single-request upload is simple. For long videos or mobile networks, a failed request should not force the user to resend the entire file. A resumable protocol tracks an upload identifier and the committed byte offset so the client can continue from a known point.

    Persist state on both sides

    The server must bind the upload session to a user, expected size, expiration, and destination. The client should save the upload ID and query the server’s current offset after reconnecting instead of trusting its local counter. Progress means bytes accepted by the server, not just bytes sent by the browser.

    Finish exactly once

    After the final chunk, verify length and checksum, then create or finalize one asset record. Expire incomplete uploads and reclaim their storage. Test interrupted requests, duplicate chunks, browser refreshes, and two tabs resuming the same session before relying on the happy path.

    A concrete acceptance test

    Interrupt a large upload halfway, restart the browser, and resume from the server-reported offset. Repeat the last chunk and confirm that the final checksum and asset count remain correct. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

    Implementation check

    • Resume from the server offset after reconnecting.
    • Bind each session to an owner, size, and expiration.
    • Check the completed length and checksum before publication.

    Related guides

    Primary reference: Official documentation.

    Related field note

    Continue with The maintenance burden behind resumable upload protocols.

  • Direct browser uploads without exposing storage credentials

    Direct browser uploads without exposing storage credentials

    How to let browsers upload large media while the application keeps control.

    Issue a narrow upload grant

    The browser asks your application for permission, then uploads to object storage using a short-lived presigned URL. The application should choose the destination key and enforce the user’s quota before signing. A presigned URL inherits the signer’s permissions, so scope the signing identity and expiration carefully.

    Confirm the object after upload

    A successful browser request does not finish the workflow. Have the client call a completion endpoint, or consume a trusted storage event, then verify the object exists and its measured size and type are acceptable. Only then move the asset from pending to processing. Record a request ID so retries cannot create duplicate asset records.

    Avoid predictable overwrite paths

    An upload to an existing object key can replace that object. Generate opaque keys instead of using the original filename as the storage key. Keep the human filename as metadata after validation. Expire unused upload grants and clean up abandoned pending objects with a lifecycle policy.

    A concrete acceptance test

    Request an upload grant as one user, try it with an oversized file, and attempt a second upload to the same key. Confirm that the grant cannot overwrite an already published asset. Run this test with a realistic asset and record the observed state, output URL, and failure reason.

    Implementation check

    • Sign only a generated key for an authorized user.
    • Verify size and type after storage confirms the upload.
    • Expire abandoned grants and clean up pending objects.

    Related guides

    Primary reference: Official documentation.

    Related field note

    Continue with A migration plan for direct browser uploads.