#Image Optimization
Compile-time, WebP-first responsive images with the Image component.
<Image> is a compile-time image pipeline: it generates a responsive,
WebP-first <picture> for every image referenced in your pages, using a
pure-Go encoder with no native dependencies. There is no runtime image server,
no network requests to an optimizer, and nothing to configure per request.
#How it works
During krate build, <Image> compiles each source file into variants written
to .krate/cache/images/ and copied to <outDir>/_krate/images/ (served at
/_krate/images/...). The rendered markup is a <picture> element:
- WebP + fallback pair - every size is emitted twice: a
<source type="image/webp">with a lossy WebP variant, and a<source>in the original codec (JPEG, or PNG when the source has transparency). The<img>falls back to the untouched original file for browsers without<picture>support. - Responsive
srcset- without awidth/height, sources at theimages.breakpoints(default640 / 768 / 1024 / 1280 / 1536, then the original width) for both codecs, plus asizesattribute you set per use site:<Image sizes="(max-width: 768px) 100vw, 50vw" />. With awidth(orheight) the image is shown at that size, so only 1x and 2x variants are made (width={100}gives 100w and 200w, never wider than the source) andsizesdefaults to"100px". An explicitsizesalways wins. - Orientation - a JPEG with an EXIF orientation (most phone photos) is rotated before it is resized, so the variants and the reported dimensions match what the browser shows for the original. Other EXIF data is not copied.
- GIF - a still GIF is converted like a PNG; an animated GIF is served unchanged (re-encoding would keep only the first frame).
- CLS mitigation -
widthandheightattributes plusstyle="max-width:100%;height:auto;aspect-ratio:W/H"reserve space before the image paints. The image is never stretched past itswidth. With onlywidth(orheight) the other dimension follows the source ratio; with both, the image is cropped to that box withobject-fit:cover. Astyleyou pass is merged into the same attribute (yours wins). - Lazy by default -
loading="lazy"withdecoding="async"; addpriorityforeagerloading withfetchpriority="high". - Blur placeholder (LQIP) - a 16px box-blurred, base64 data-URI rendered
as the element's
background-imageuntil the real image loads (placeholder="blur", the default). Useplaceholder="empty"to disable.
#Errors and warnings
<Image> problems fail the build with a file:line:col diagnostic and a hint,
instead of shipping a broken image:
KR8801- the source file is missing or cannot be decoded.KR8802- a remotesrcwhose host is not inimages.remotePatterns.KR8803-src,width,height,qualityorpriorityis not known at build time. Aconstinitialised with a literal works;alt,sizesandclassNamemay be expressions.KR8804(warning) - noalt. Writealt=""for decorative images.
With a basePath, the generated src and srcset URLs are prefixed with it.
#Props reference
The full prop surface is documented on the
Built-in Components page under
<Image>. The essential controls are src, width, height (or
width/quality and the intrinsic ratio for the rest), quality,
sizes, loading, priority, and placeholder.
#Quality
quality (0-100, default depends on the source codec) controls the WebP
encode and, where applicable, the fallback re-encode. JPEG re-encodes for the
WebP variant only; the fallback stays lossless from the original for PNG
sources.
#Default OG image
Configured once in krate.config.ts, the SEO default image is used for
og:image on every page that does not already declare one in its <Head>:
// krate.config.ts
export default defineConfig({
site: {
url: "https://example.com",
name: "Example",
image: "/og-default.png",
},
});A relative image is resolved against site.url; an absolute http(s)
URL is used as-is. Per-page <Head> markup always wins over the default, and
Krate never duplicates an og:image tag the page already emits.
Last updated: 2026-11-17
Contributors: Noinkin