Images

The images block declares which sources may be optimized, which sizes and formats are allowed, and any named variants.

An images block is the policy the edge enforces when it resizes and re-encodes an image. It is a whitelist first and a set of defaults second: a request asking for a width or a source host the policy does not list is rejected rather than served.

Declaring a policy

version: 4

images:
  remotePatterns:
    - protocol: https
      hostname: cdn.example.com
      pathname: /images/**
  widths: [640, 1080, 1920]
  qualities: [60, 80]
  formats: [image/avif, image/webp]
  minimumCacheTTL: 86400
  variants:
    thumb:
      width: 320
      height: 320
      fit: cover
      format: image/webp

Every sub-key is optional. Whether the block is there at all is not: omitting images emits no policy, and writing it fills in every key you leave out from the defaults in the following table. The keys are strict, so a typo such as qualitys fails the build with a validation error rather than being ignored.

Keys

Key	Type	Accepted	Default
`widths`	list of integers	1 to 64 unique values, each 1 to 8192	`[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`
`heights`	list of integers	up to 64 unique values, each 1 to 8192	`[]`
`qualities`	list of integers	1 to 100 unique values, each 1 to 100	`[75]`
`formats`	list of media types	1 to 4 of `image/avif`, `image/webp`, `image/jpeg`, `image/png`	`[image/avif, image/webp]`
`localPatterns`	list of objects	up to 64 entries	`[{ pathname: /** }]`
`remotePatterns`	list of objects	up to 64 entries	`[]`
`minimumCacheTTL`	integer, seconds	0 to 31536000	`14400`
`dangerouslyAllowSVG`	boolean		`false`
`contentSecurityPolicy`	string	4096 characters at most	`default-src 'self'; script-src 'none'; sandbox;`
`contentDispositionType`	string	`inline` or `attachment`	`attachment`
`maximumRedirects`	integer	0 to 10	`3`
`maximumResponseBody`	integer, bytes	1024 to 104857600	`52428800`
`variants`	map	up to 100 named entries	`{}`

A width or quality that is not in its list is refused, which is what keeps an open image endpoint from becoming an unbounded transform farm. dangerouslyAllowSVG carries its name for a reason: SVG is executable markup, and the contentSecurityPolicy and contentDispositionType defaults are what contain it when you turn it on.

Which sources may be optimized

localPatterns govern paths inside your own deployment, and each entry takes a pathname glob and an optional search string. remotePatterns govern everything else. An entry needs a hostname and may add protocol (http or https), port, pathname, and search. A remote host that matches no entry is refused before any fetch happens, so an empty remotePatterns list means local sources only.

Variants

A variant is a named bundle of transform parameters, asked for with a variant query parameter instead of spelling out the size and format on every request. A name is up to 64 characters of letters, digits, underscores and hyphens, starting with a letter or digit, and each variant sets at least one of width, height, quality, format, and fit. fit is one of contain, cover, fill, inside, or outside.

Parameters on the request win over the variant's values, so asking for thumb with a quality of 60 keeps that variant's dimensions and overrides its quality. A name no variant matches returns 400. Image optimization covers the request URL itself.

Not applied when a framework is detected

An images block reaches the edge on a project where framework detection finds nothing. When a project has both a config file and a detected framework, the two are combined and the image policy is not carried across, so the block is dropped and image requests return 404. A framework project deployed without a gigadrive.yaml keeps the policy its adapter generated.