<Image>

import { Image } from "@pylonsync/react";

<Image
  src="/hero.jpg"
  alt="Mountain at dawn"
  width={1200}
  height={800}
/>

<Image> renders a plain <img> pointing at Pylon’s built-in optimizer endpoint. The browser fetches an AVIF or WebP (or JPEG, depending on Accept) sized for the user’s viewport, served from disk cache on every subsequent request. The pipeline is written in Rust: image decodes the source, fast_image_resize (SIMD) resizes it, and ravif / rav1e (AVIF), libwebp, and mozjpeg encode the output. It needs no Sharp install, no libvips on the host, and no Node child process. Everything runs inside the Pylon binary.

What it does

For a single <Image src="/hero.jpg" width={1200} height={800} />:

Renders <img srcset> with multiple width candidates (default: 1x and 2x of width, capped at 3840px).
Each candidate points at /_pylon/image?src=/hero.jpg&w=<width>&q=<quality>.
Browser picks the smallest candidate that satisfies the viewport DPR.
Server decodes once, resizes with SIMD (Lanczos3), encodes as AVIF, WebP, or JPEG depending on Accept.
Result is hashed by (src, width, quality, format) and cached at .pylon/.cache/images/<hash>.<ext>. A cache hit skips decode and encode. It serves the file directly.
Response carries Cache-Control: public, max-age=31536000, immutable.

API

interface ImageProps {
  /** Source — site-relative ("/foo.jpg") or http(s) URL (allowlisted via env). */
  src: string;
  /** Intrinsic width in CSS px. Used for aspect ratio + the 1x srcset candidate. */
  width: number;
  /** Intrinsic height in CSS px. */
  height: number;
  /** Required alt text. Pass "" for purely decorative images. */
  alt: string;
  /** JPEG/WebP quality 1..=100. Default 75. PNG ignores it. */
  quality?: number;
  /** Override srcset widths. Default: [width, width*2] capped at 3840. */
  widths?: number[];
  /** `<img sizes>`. Default "100vw" — tighten for grid layouts. */
  sizes?: string;
  /** Skip lazy-loading, bump fetchPriority to "high". Use for above-the-fold heroes. */
  priority?: boolean;
  /** Plus any other <img> attribute (className, style, onClick, etc.). */
}

Examples

Hero image (above the fold)

<Image
  src="/hero.jpg"
  alt="Mountain at dawn"
  width={1920}
  height={1080}
  priority
  sizes="100vw"
  className="w-full h-[60vh] object-cover"
/>

priority skips loading="lazy" and sets fetchPriority="high" so the browser prioritizes it during the initial paint.

Responsive grid

<ul className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
  {photos.map((p) => (
    <li key={p.id}>
      <Image
        src={p.src}
        alt={p.caption}
        width={600}
        height={400}
        sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
        className="aspect-[3/2] w-full object-cover rounded-2xl"
      />
    </li>
  ))}
</ul>

The sizes attribute matters most. It tells the browser how wide the image renders at each breakpoint, so the browser picks the smallest viable srcset candidate. Without it, the browser assumes 100vw and downloads a 4K image for a 200px thumbnail.

Custom srcset

<Image
  src="/avatar.png"
  alt={user.name}
  width={64}
  height={64}
  widths={[64, 96, 128]}
  quality={85}
/>

Useful for avatar grids where you know the exact DPR multipliers you need.

Safety & configuration

The optimizer only processes images that match its safety rules. Every setting has a safe default, and you tune each one through an environment variable. The same defaults apply in pylon dev and in production.

Allowed widths

The server rejects requests whose w value is not in its width set. This stops a cache-fill denial-of-service attack, where an attacker requests thousands of slightly different widths to fill your disk.

# Defaults (mirror Next.js):
PYLON_IMAGE_DEVICE_SIZES=640,750,828,1080,1200,1920,2048,3840
PYLON_IMAGE_IMAGE_SIZES=16,32,48,64,96,128,256,384

<Image> only generates srcset URLs with widths from this combined set, so it works with the default configuration. If you customize the environment variables, also pass widths={[...]} on each <Image> to keep the srcset URLs in range.

Allowed qualities

The server applies the same defense to the q parameter.

PYLON_IMAGE_QUALITIES=50,75,90   # default

For finer control over quality, add more values: PYLON_IMAGE_QUALITIES=50,65,75,85,90,95.

Allowed formats

PYLON_IMAGE_FORMATS=avif,webp,jpeg   # default

This locks the optimizer to a specific output set. The server picks the best match for the request’s Accept header from this list. <Image> lets the server pick by default. Pass format= in your own URLs for explicit control.

Remote source allowlist

PYLON_IMAGE_REMOTE_ALLOWLIST=cdn.example.com,images.unsplash.com/photos/

Each entry is host or host/pathPrefix:

Pattern	Matches
`cdn.example.com`	any path on this exact host
`cdn.example.com/users/`	only paths starting with `/users/`
`*.example.com`	one-level wildcard: matches `foo.example.com`, not `foo.bar.example.com`

Without this environment variable, any src starting with http:// or https:// returns 400. This prevents SSRF. It stops random visitors from making your server fetch arbitrary internal URLs.

Source size cap

PYLON_IMAGE_MAX_BYTES=26214400   # 25MB default

This cap applies to both local files and remote fetches. The server rejects remote responses that exceed it mid-stream.

Pixel-bomb protection

PYLON_IMAGE_MAX_PIXELS=40000000   # 40M px (~24MP camera photo) default

A tiny PNG can declare a 100000×100000 canvas. Decoding it would allocate 40GB of RGBA data. Pylon reads the image header before decoding and rejects any source whose declared width × height exceeds this cap. The default (40M px, about 160MB peak decode) is tuned so a burst of concurrent requests cannot exhaust the memory of a small machine. Operators serving huge sources raise the cap explicitly.

Fetch timeout

PYLON_IMAGE_FETCH_TIMEOUT_MS=15000   # 15s default

This timeout applies to remote source fetches.

SVG handling

SVG is always rejected, both as input and as output. SVG can carry inline <script> tags and CSS. Serving arbitrary SVG through an optimization endpoint would create an XSS vector. There is no dangerouslyAllowSVG toggle. This is intentional. If you need SVGs, render them with a plain <img src="/icon.svg"> (not through <Image>) and serve them with Content-Security-Policy: script-src 'none'. See the unoptimized prop below.

Local file source

A src starting with / resolves under the frontend directory (PYLON_FRONTEND_DIR or <app>/web/dist). Pylon always rejects path traversal: it canonicalizes the path and checks the prefix, so .. segments and symlinks that point outside the directory return 400.

Bypassing the optimizer per-image

<Image src="/icon.svg" alt="" width={32} height={32} unoptimized />

This renders a plain <img src="/icon.svg"> with no srcset and no optimizer round trip. It is useful for SVGs, animated GIFs, or images where the source is already sized correctly.

Format selection

Request `format=` query	Behavior
`avif`	Always AVIF, lossy (ravif / rav1e).
`webp`	Always WebP, lossy (libwebp).
`jpeg` / `jpg`	Always JPEG (mozjpeg).
`png`	Always PNG (lossless).
`(omitted)`	AVIF when `Accept` explicitly advertises `image/avif`; otherwise WebP when the client accepts it or sends no `Accept` (the universal fallback); otherwise JPEG.

Pylon serves AVIF automatically to browsers that advertise image/avif (Chrome, Firefox, Safari 16+). AVIF is the smallest of the three formats. The tradeoff is a slower cold encode (rav1e at speed 8), which the on-disk cache reduces to a one-time cost per (src, width, quality) combination. Browsers that do not advertise AVIF fall back to WebP, still about 30% smaller than mozjpeg at the same perceptual quality. Unknown clients (curl, or bots that send no Accept header) also get WebP.

Performance

Benchmarks on a 2400×1600 source JPEG (~250KB) on Apple Silicon:

Operation	Time
Cold: decode + Lanczos3 resize to 1200×800 + WebP encode	46–74ms
Cold: same path + JPEG (mozjpeg) encode	50–80ms
Hot: cache hit, served from disk	9ms (file serve only)
WebP output size @ q=75	35KB (7.7× smaller than source)
JPEG output size @ q=75	51KB (5.4× smaller than source)

Tail latency is bounded by the encoder. Cache hits are bounded by your disk. For high-traffic sites, put a CDN in front of Pylon. Pylon never reprocesses an image once its immutable URL is cached.

Env reference

Env	Default	Purpose
`PYLON_FRONTEND_DIR`	`<app>/web/dist`	Source root for local (`/path`) images.
`PYLON_IMAGE_REMOTE_ALLOWLIST`	(empty)	`host` or `host/pathPrefix` entries for `http(s)://` sources. Empty = local only.
`PYLON_IMAGE_DEVICE_SIZES`	`640,750,828,1080,1200,1920,2048,3840`	Allowed widths (full-bleed).
`PYLON_IMAGE_IMAGE_SIZES`	`16,32,48,64,96,128,256,384`	Allowed widths (thumbnails).
`PYLON_IMAGE_QUALITIES`	`50,75,90`	Allowed quality values.
`PYLON_IMAGE_FORMATS`	`avif,webp,jpeg`	Allowed output formats.
`PYLON_IMAGE_MAX_BYTES`	`26214400` (25MB)	Source byte cap.
`PYLON_IMAGE_MAX_PIXELS`	`40000000` (40M, ~24MP)	Decoded pixel cap. Pixel-bomb protection.
`PYLON_IMAGE_FETCH_TIMEOUT_MS`	`15000`	Remote-source fetch timeout.

The cache lives at <cwd>/.pylon/.cache/images/. Delete it to force regeneration. There is no LRU eviction yet. Content-addressed entries are append-only, so the cache grows with the variety of (src, width, quality, format) combinations you serve. In production this is rarely a problem: the full set of a site’s images is usually under 1GB. A pylon cache clean command will arrive when it matters.

Differences from Next.js’s `<Image>`

	Pylon `<Image>`	Next.js `<Image>`
Backend	Built-in Rust pipeline	Sharp (libvips, separate npm install)
Formats	AVIF, WebP, JPEG, PNG	AVIF, WebP, JPEG, PNG
Sources	Local + remote with host + path-prefix patterns	Local + remote with `images.remotePatterns`
Width allowlist	`PYLON_IMAGE_DEVICE_SIZES` + `PYLON_IMAGE_IMAGE_SIZES`	`deviceSizes` + `imageSizes`
Quality allowlist	`PYLON_IMAGE_QUALITIES`	`qualities`
Format allowlist	`PYLON_IMAGE_FORMATS`	`formats`
Source size cap	`PYLON_IMAGE_MAX_BYTES` (25MB default)	`contentLengthLimit`
Pixel-bomb cap	`PYLON_IMAGE_MAX_PIXELS` (100M default)	implicit (Sharp’s `limitInputPixels`)
SVG	always rejected (no toggle)	`dangerouslyAllowSVG` opt-in
Per-image bypass	`<Image unoptimized />`	`<Image unoptimized />`
Placeholder	Pass a CSS color or data URI yourself	Built-in `placeholder="blur"` with auto-generated blur data
Static import	Not yet	Yes (resolves intrinsic dims at compile time)

placeholder="blur" is on the roadmap. SVG support is deliberately off the roadmap. Render SVG with a plain <img> tag, not through <Image>.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

What it does

API

Examples

Hero image (above the fold)

Responsive grid

Custom srcset

Safety & configuration

Allowed widths

Allowed qualities

Allowed formats

Remote source allowlist

Source size cap

Pixel-bomb protection

Fetch timeout

SVG handling

Local file source

Bypassing the optimizer per-image

Format selection

Performance

Env reference

Differences from Next.js’s `<Image>`

​What it does

​API

​Examples

​Hero image (above the fold)

​Responsive grid

​Custom srcset

​Safety & configuration

​Allowed widths

​Allowed qualities

​Allowed formats

​Remote source allowlist

​Source size cap

​Pixel-bomb protection

​Fetch timeout

​SVG handling

​Local file source

​Bypassing the optimizer per-image

​Format selection

​Performance

​Env reference

​Differences from Next.js’s <Image>

What it does

API

Examples

Hero image (above the fold)

Responsive grid

Custom srcset

Safety & configuration

Allowed widths

Allowed qualities

Allowed formats

Remote source allowlist

Source size cap

Pixel-bomb protection

Fetch timeout

SVG handling

Local file source

Bypassing the optimizer per-image

Format selection

Performance

Env reference

Differences from Next.js’s `<Image>`