Image Optimization

Resux's default image provider generates transformation URLs served from /__resux/image. The image runtime supports dimensions, quality, format, fit, provider modifiers, optional generated-cache metadata, and responsive URL generation.

useResuxImage()

useResuxImage() returns the same style of image URL builder used by the template renderer.

const image = useResuxImage()

const hero = image('/images/hero.jpg', {
  width: 1200,
  height: 675,
  quality: 82,
  format: 'webp',
  fit: 'cover',
  cache: '7d'
})

Signature

function useResuxImage(): ResuxImageBuilder

type ResuxImageBuilder = (
  src: string,
  options?: UseResuxImageOptions
) => string

UseResuxImageOptions

Property	Type	Description
provider	string	Provider/config key.
modifiers	ResuxImageModifiers	Additional merged provider modifiers.
width	number	Requested transform width.
height	number	Requested transform height.
quality	number	Requested output quality.
fit	ResuxImageFit	Resize fit.
format	string	Requested output format.
cache	ResuxImageCacheInput	Cache duration/policy input.

ResuxImageFit is:

type ResuxImageFit =
  | 'cover'
  | 'contain'
  | 'fill'
  | 'inside'
  | 'outside'

ResuxImageModifiers also allows provider-specific string/number/boolean keys. format: false and quality: false are recognized as explicit disabling values when modifiers are normalized.

Global configuration

export default defineResuxConfig({
  image: {
    provider: 'resux',
    quality: 82,
    format: 'webp',
    cache: '7d',
    densities: [1, 2],
    providers: {
      cdn: {
        baseURL: 'https://cdn.example.com',
        modifiers: {
          quality: 80
        }
      }
    }
  }
})

The resolved modifier order allows provider defaults and global quality/format to be combined with per-call options/modifiers; more specific call values override the broader defaults.

Provider URL behavior

• Provider resux defaults to /__resux/image.
• Provider vercel defaults to /_vercel/image.
• A configured provider can supply baseURL.
• Provider base URLs containing a {src} token are handled as source templates by the builder.

Do not assume an arbitrary third-party CDN understands Resux query names. A custom base URL/provider must match the transformation contract expected by that service.

Transformation bounds

The built-in server path validates image transformation inputs. The current documented bounds include:

• width: 1–8192
• height: 1–8192
• quality: 1–100
• fit: cover | contain | fill | inside | outside

The implementation uses sharp for real image transformations. When a requested transform cannot be performed, Resux should fail rather than silently claim that an untouched original satisfies the requested output.

Sharp deployment requirement

If your production path uses Resux image transformation, install a Sharp build compatible with the deployment OS/architecture. A development machine's native package result is not proof that a serverless/edge deployment has the same binary support.

Test the production target declared in your Resux deployment configuration.

Cache input

The cache option accepts:

type ResuxImageCacheInput =
  | boolean
  | string
  | number
  | {
      maxAge?: number | string
      expiresIn?: number | string
      ttl?: number | string
    }

Duration strings used by the current media path include values such as:

30m
12h
7d
2w

Generated image cache metadata can record the transform key, creation/expiry timestamps, source, generated path, modifier settings, and source-file modification details where available.

Generated caches are build/runtime artifacts; do not commit them unless your deployment process explicitly treats them as deployable artifacts.

Stateless serverless cache behavior

Starting with Resux 0.3.10, cached generated image and video URLs are safe on stateless serverless runtimes such as Vercel, AWS Lambda, and Netlify-style functions.

A deployed function filesystem must not be treated as a writable persistent media cache. On those runtimes, Resux keeps the public hashed generated-media URL contract but internally routes cached generated requests through the stateless /__resux/image or /__resux/video transform handler. The requested cache duration is then expressed in browser/shared-cache headers, including provider-specific CDN headers where supported.

For example, cache="7d" results in a seven-day public/shared-cache TTL for a successful generated response rather than trying to create a persistent generated file under the deployed application directory. cache: true uses the framework's one-day default cache lifetime; numeric values are seconds, and duration strings such as 30m, 12h, 7d, and 2w are converted to positive TTLs.

Resux emits the requested TTL in these headers for successful stateless generated-media responses:

Cache-Control: public, max-age=<seconds>, s-maxage=<seconds>
X-Resux-Cache: stateless
CDN-Cache-Control: public, max-age=<seconds>
Vercel-CDN-Cache-Control: public, max-age=<seconds>

Cache-Control and X-Resux-Cache describe the general Resux response behavior. CDN-Cache-Control and Vercel-CDN-Cache-Control are provider-specific cache hints and only affect deployments that recognize them; Vercel-CDN-Cache-Control is intended for Vercel. Other providers may ignore unsupported CDN-specific headers.

Do not add app-level scripts that copy, write, or patch generated media into a Vercel function's public directory. If serverless generated media fails because of filesystem writes, fix or upgrade the framework runtime instead.

Static, unchanged files are a different case: keep them in public/ or dedicated object/CDN storage and let the hosting platform serve them directly. Only use the generated transform endpoints when you actually need resizing, reformatting, quality changes, or video transformation.

Remote-source security

/__resux/image can cause server-side network access for remote inputs. This is a security boundary, not just a performance feature.

Production guidance:

• allow only trusted remote origins at the application/reverse-proxy layer;
• block private-network/metadata endpoints from user-controlled URLs;
• enforce request and response size limits;
• enforce timeouts;
• never put credentials in image source URLs;
• apply CDN caching for public high-volume transformed assets;
• validate provider base URLs and CSP/network policies.

The framework's URL builder does not replace infrastructure-level SSRF controls.

Performance checklist

• Declare width and height.
• Use sizes that matches layout.
• Prefer modern formats only when your transform/deployment path supports them.
• Tune quality visually; do not automatically set 100.
• Keep LCP images eager/high priority; lazy-load below-the-fold media.
• Cache immutable transformations for long periods when source versioning makes that safe.
• Avoid transforming the same source into excessive near-identical widths.
• Put public immutable transformed output behind a CDN where appropriate.
• Serve unchanged static images/video directly instead of sending them through a transformation function.
• On serverless, rely on CDN/shared-cache headers rather than runtime filesystem persistence.

Related

• Images
• Responsive Images
• Video
• Security and Caching