Image Optimization

Installation

This plugin is included in fumapress, and enabled automatically under the recommended preset (the default) with a provider matching your deployment target, detected from the environment like the deployment adapter:

• Vercel: uses Vercel Image Optimization, works with static mode.
• Cloudflare: uses Cloudflare Image Transformations via /cdn-cgi/image/, works with static mode when your zone has transformations enabled.
• Self-hosted (Node.js): runs a dynamic optimization endpoint powered by Sharp. It requires Sharp to be installed, and cannot be served statically:

npm i sharp

On other targets, or when the requirements above aren't met, image optimization is skipped and the Image component renders a plain <img>.

To customize options, add the plugin explicitly in your Fumapress config (it takes priority over the detected provider):

import { defineConfig } from "fumapress";
import { imagePlugin } from "fumapress/plugins/image/vercel";

export default defineConfig({
  // ...
})
  .plugins(
    imagePlugin({
      // See https://vercel.com/docs/project-configuration/vercel-json#images
    }),
  );

Usage

Use the Image component from fumapress/image.

import { Image } from "fumapress/image";

export default function Hero() {
  return <Image src="/hero.png" alt="Hero" width={1200} height={630} className="rounded-lg" />;
}

When image optimization is enabled, it generates responsive srcSet values and serves optimized formats automatically. This allows the browser to pick a suitable size of image, and compress the size of images.

Remote images must be explicitly allowed (self-hosted), match your Vercel image configuration, or be permitted in your Cloudflare zone's transformation settings. Local paths such as /logo.png are always allowed. You can also pass the unoptimized prop to serve an image as-is.

SVG images are not optimized by default.

Options

Vercel provider

These options are written to your Vercel build output during production builds. See Vercel image configuration for details.

import { imagePlugin } from "fumapress/plugins/image/vercel";

export default defineConfig({
  // ...
}).plugins(
  imagePlugin({
    formats: ["image/webp", "image/png"],
    remotePatterns: [
      {
        protocol: "https",
        hostname: "cdn.example.com",
        pathname: "/assets/**",
      },
    ],
  }),
);

Cloudflare provider

Enable Image Transformations on your zone before deploying. Remote sources are controlled in the Cloudflare dashboard, not in this plugin.

import { imagePlugin } from "fumapress/plugins/image/cloudflare";

export default defineConfig({
  // ...
}).plugins(
  imagePlugin({
    format: "auto",
    fit: "scale-down",
  }),
);

Self-hosted provider

import { imagePlugin } from "fumapress/plugins/image/self-hosted";

export default defineConfig({
  // ...
}).plugins(
  imagePlugin({
    allowedHosts: [
      "images.example.com",
      {
        protocol: "https",
        hostname: /cdn\.example\.com/,
        pathname: /^\/assets/,
      },
    ],
  }),
);

In development, invalid image sources throw immediately. In production, disallowed sources return 403.