Image Optimization

Installation

This plugin is included in fumapress.

Choose a provider based on where you deploy:

• 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 — runs a dynamic optimization endpoint powered by Sharp, cannot be served statically.

Install Sharp when using the self-hosted provider:

npm i sharp

Enable the plugin in your Fumapress config:

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.

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.