Skip to content

Private previewMost of the architecture is written. First public release in 2027.

Images

@hamur/image turns one image file into the sizes and formats a page needs: Img and Picture components for React, Vue, Preact, Svelte and Solid (plain functions for html), and getImage and getSizes for a handler. It sets width, height, srcset and sizes, lazy loading, an optional blur placeholder and an LCP preload, and it picks where the transform runs for your deploy target.

sh
bun add @hamur/image
ts
import { defineConfig } from "hamur";

export default defineConfig({
  framework: "react",
  modules: ["@hamur/image"],
  image: {
    format: ["webp"],
    quality: 75,
    widths: [320, 640, 960, 1280, 1920],
    domains: ["images.example.com", "https://cms.example.com/uploads/**"],
    presets: { avatar: { modifiers: { width: 64, height: 64, fit: "outside" } } },
  },
});

Add the module to modules; its options live under the image key. With the module in modules, Img and Picture are also registered as components of your app; the samples below import them from @hamur/image/<library> to show where they come from, and getImage and getSizes are imported the same way. Every option is in the reference.

Showing an image

src is a path below public/, an asset import, a remote URL, an alias path or a ?meta object. alt is required; "" marks a decorative image. width and height default to the file's own size when Hamur can read it, so the browser reserves the space before the image loads.

tsx
import { Img, Picture } from "@hamur/image/react";
import hero from "./hero.jpg?meta";
import blur from "./hero.jpg?placeholder";
import Logo from "./logo.svg?component";

export default function Home() {
  return (
    <main>
      <Logo className="logo" width={32} title="Hamur" />
      <Img src={hero} alt="A lake at dawn" sizes="100vw md:50vw" placeholder={blur} preload />
      <Picture src="/photos/b.png" width={600} format={["avif", "webp"]} alt="" />
      <Img src="/photos/a.jpg" preset="avatar" alt="Ada" />
    </main>
  );
}

Img renders one <img> whose src, srcset and sizes come from getSizes. sizes="100vw md:50vw" reads as "full width, half width from the md screen up"; the screens and densities options set the breakpoints and the pixel ratios. Picture renders one <source> for each format in format that the provider makes, then an <img> in the legacyFormat that every browser reads. preload is for the page's LCP image: it adds a preload link to the head and sets loading="eager" and fetchpriority="high". preset="avatar" takes the modifiers of image.presets.avatar.

The other libraries take the same props:

vue
<script setup lang="ts">
import { Img, Picture } from "@hamur/image/vue";
</script>

<template>
  <main>
    <Img src="/photos/a.jpg" :width="1200" sizes="100vw md:50vw" alt="A lake at dawn" preload />
    <Picture src="/photos/b.png" :width="600" :format="['avif', 'webp']" alt="" />
  </main>
</template>
svelte
<script lang="ts">
  import { Img, Picture } from "@hamur/image/svelte";
</script>

<main>
  <Img src="/photos/a.jpg" width={1200} sizes="100vw md:50vw" alt="A lake at dawn" preload />
  <Picture src="/photos/b.png" width={600} format={["avif", "webp"]} alt="" />
</main>

html has no tags: import the functions from @hamur/image/html and put the string they return in your page.

ts
import { Img, Picture } from "@hamur/image/html";

export default function Home(): string {
  return [
    Img({ src: "/photos/a.jpg", width: 1200, sizes: "100vw md:50vw", alt: "A lake at dawn", preload: true }),
    Picture({ src: "/photos/b.png", width: 600, format: ["avif", "webp"], alt: "" }),
  ].join("");
}

Every prop is in the Img and Picture reference.

Image URLs in a handler

getImage and getSizes read the same generated config as the components, so a handler, an OpenGraph tag and a component give one answer.

ts
import { getImage, getSizes } from "@hamur/image/server";
import { defineHandler } from "hamur/server";

export const apiImage = defineHandler({
  route: "/api/image",
  method: "GET",
  raw: true,
  handler() {
    return {
      photo: getImage("/photos/a.jpg", { width: 600 }).url,
      avatar: getImage("/photos/a.jpg", {}, { preset: "avatar" }).url,
      sizes: getSizes("/photos/a.jpg", { sizes: "100vw md:50vw" }),
    };
  },
});

getImage(src, modifiers, { provider, preset }).url is the URL; getSizes returns { src, srcset, sizes, width, height }. With the hamur provider the URL is /_hamur/image/<modifiers>/<source>.<ext>, for example /_hamur/image/q_75,v_3f9a01c2,w_640/photos/a.jpg.webp; v_ pins the file's content, so the URL changes when the file does.

Widths

A transform is made at a width from a fixed list, never at an arbitrary one, so a visitor cannot ask your server for ten thousand sizes. image.widths is that list. By default it is every screens value times every densities value, plus 64, 128, 256 and 384. A width you ask for is rounded up to the next entry and then capped at the source's own width; a source is never enlarged. The hamur route refuses any other width with a 400. Set widths to match the layout:

ts
image: { widths: [320, 640, 960, 1280, 1920] }

On vercel, the same list is written to images.sizes of the Vercel config, since Vercel refuses a width outside it.

Providers and where transforms run

A provider turns a source and modifiers into a URL. image.provider defaults to "auto": the platform's own service on vercel and netlify, and the built-in hamur provider everywhere else.

Presetauto picksWhere transforms runAVIF
bunhamurat request, by Bun.Image in the server; results kept in the cache storage mountno
nodehamurat build: each variant is a file in .output/public/_hamur/image/no
statichamurat build, as nodeno
cloudflarehamurat build; provider: "cloudflare" moves them to the zone's Image Transformations, which you turn onwith the cloudflare provider, chosen by Accept
vercelvercelat request, by Vercel's image optimisationwhen image.format lists avif
netlifynetlifyat request, by the Netlify Image CDNyes, by Accept

Under hamur dev every preset uses hamur at request time, so a dev server needs no build step. The rule behind the table is the preset's features.imageTransforms: the hamur provider transforms at request where it is not unsupported (only bun today) and at build elsewhere; features.imageService names the platform service (vercel, netlify) that auto picks. A build that transforms at build time writes every variant its prerendered pages use, plus the sources in image.prerender; a server preset answers a variant that was not written with a 404.

The hamur provider makes JPEG, PNG and WebP only. Bun.Image encodes AVIF only where the operating system has an AV1 encoder (never on Linux), and the same URL would then hold AVIF on one machine and WebP on another. Listing avif in image.format with hamur in use logs a build warning and avif is used by the other providers only. SVG and GIF sources are not transformed by hamur; link them directly.

Besides hamur, none (the src as given), vercel, netlify and cloudflare, fifteen hosted services have a provider: cloudinary, imgix, imagekit, cloudflareImages, bunny, fastly, sanity, storyblok, contentful, strapi, supabase, uploadcare, twicpics, imgproxy and weserv. Name one under image.providers with its options. Only the providers a build names are in its bundle. See Hosted providers for each one's options.

ts
import { defineConfig } from "hamur";

export default defineConfig({
  framework: "react",
  modules: ["@hamur/image", "@hamur/blob"],
  image: {
    provider: "cloudinary",
    providers: { cloudinary: { options: { cloudName: "demo" } } },
    sources: { blob: { prefix: "/blob/" } },
  },
});

imgproxy builds unsigned /insecure/ URLs only, so restrict its sources in the service. A provider option named key, secret or salt fails the build: a URL signed in your config would put the secret in the bundle.

A provider of your own is a file that default-exports an object satisfies ImageProvider and is named in image.providers.<name>.provider; see ImageProvider.

Remote images and limits

A remote src is transformed only when image.domains allows its host, or an image.alias target does. domains takes host patterns (cdn.example.com, *.example.com for one label, **.example.com for any depth) and URL patterns that fix scheme, port and path; "*" is a build error. The hamur route also protects your server:

  • a host that resolves to a loopback, private, link-local or unspecified address is refused with 403, and the request goes to the address that was checked;
  • at most 3 redirects, each target checked again;
  • 10 seconds, then 504;
  • image.maxBytes (25 MiB) of body and image.maxPixels (50 million) of pixels, then 413.

A URL with a query string cannot be a build-time file; hamur build fails and tells you to use a provider for that source.

Images in a blob store

With @hamur/blob in modules, image.sources.blob.prefix (such as "/blob/") makes every src below the prefix a blob key, transformed where the route runs (bun and hamur dev). Every key below the prefix is publicly readable through /_hamur/image/: a guard you put around useBlob().serve does not apply. Keep private files outside the prefix. On a preset that transforms at build, the build warns and such a src is returned as it is.

Placeholders, sizes and inline SVG

Three import queries prepare an image at build time. They are described under Assets; here is how they meet the module.

  • import blur from "./hero.jpg?placeholder" is a data:image/png;base64,… string: a ThumbHash blur of at most 32 px, measured at 0.9 to 2.6 KB. Pass it as placeholder to Img or Picture; it paints as the background until the image loads. It takes PNG, JPEG, WebP and GIF.
  • import hero from "./hero.jpg?meta" is { src, width, height, format } (ImageMeta). Img and getImage take it as src and know the size without reading the file. readImageMeta of hamur/kit reads the same header for a file a module holds.
  • import Logo from "./logo.svg?component" renders the SVG inline, so CSS and currentColor reach it. The build keeps only what is safe in a page, so <style> and class are dropped and only presentation attributes (fill, stroke, ...) stay: export your SVGs with presentation attributes, as Figma does by default and Illustrator does with its "Presentation Attributes" option. begin and end of an animation keep offsets, indefinite, wallclock() and bare events, and lose the rest.

Reference

The @hamur/image reference lists every option, the hamur route and its refusals, Img, Picture, getImage and getSizes. A module that wants its own components or public files uses addComponent and addPublicAssets.