@capri-js/image 🏞️

An image optimization library for Capri websites. This package provides an image component to automatically optimize images at build time, generating multiple sizes and formats for responsive web applications.

Features

• 🔪 Automatic image optimization with Sharp
• 📱 Responsive image generation with appropriate srcset and sizes
• 🗜️ Support for modern image formats (WebP, optional AVIF)
• 🧩 Framework components for both React and Preact
• 📐 Automatic width and height detection
• 💾 Intelligent caching for faster builds

Installation

npm install @capri-js/image

Usage

import { Image } from "@capri-js/image";

function MyComponent() {
  return (
    <Image
      src="/path/to/image.jpg"
      alt="Description of the image"
      // Optional props
      sizes="(min-width: 768px) 500px, 100vw"
      loading="lazy" // or "eager"
    />
  );
}

For Preact, import from @capri-js/image/preact instead. The API is identical.

Props

Required Props

src

Type: string

Path to the source image relative to your public directory. This image will be optimized at build time, generating multiple sizes and formats for optimal delivery.

alt

Type: string

Alternative text for the image. This is required for accessibility and should provide a meaningful description of the image content.

Optional Props

sizes

Type: string
Default: "(min-width: 500px) 500px, 100vw"

The CSS sizes attribute that tells browsers what size the image will be displayed at different breakpoints. This helps browsers choose the right image size from the generated srcset. For example:

• "(min-width: 768px) 500px, 100vw" means the image will be 500px wide on screens wider than 768px, and full viewport width otherwise
• "300px" for a fixed-size image
• "50vw" for an image that's always half the viewport width

deviceSizes

Type: number[]
Default: [375, 500]

An array of viewport widths to generate images for. The component will create optimized versions of your image at each of these widths. Use this to customize the responsive image sizes based on your design's breakpoints. For example, [320, 640, 960, 1280] would generate four different sizes of your image.

resolutions

Type: number[]
Default: [1]

Device pixel ratios to support. Add 2 to support retina displays, or even 3 for high-DPI displays. Each resolution will be combined with the deviceSizes to generate the appropriate image sizes. For example, with deviceSizes: [500] and resolutions: [1, 2], images of both 500px and 1000px width will be generated.

loading

Type: "lazy" | "eager"
Default: "lazy"

Controls the loading behavior of the image:

• "lazy": The image will only be loaded when it approaches the viewport, saving bandwidth for off-screen images
• "eager": The image will be loaded immediately, useful for above-the-fold images that should appear as soon as possible

attributes

Type: (src: string) => Record<string, any>

A callback function that receives the optimized image URL and returns additional HTML attributes to be applied to the img element. This is useful for adding custom styling or behavior based on the processed image. For example:

<Image
  src="/image.jpg"
  alt="Description"
  attributes={(src) => ({
    style: {
      shapeOutside: `url(${src})`,
      shapeMargin: "2em",
    },
  })}
/>

How It Works

1. During the build process, the library analyzes your images and generates optimized versions in multiple sizes and formats
2. The component automatically selects the appropriate image size based on the viewport and device pixel ratio
3. Images are served in modern formats like WebP (and optionally AVIF when it provides better compression)
4. The component sets proper width, height, and srcset attributes for optimal loading performance

Cache Location

Optimized images are cached to speed up subsequent builds. The cache location is determined in the following order:

1. The CAPRI_IMAGE_CACHE environment variable if set
2. The npm cache directory (from npm config get cache)
3. Fallback to .cache/image-cache in your project directory

You can set a custom cache location by setting the CAPRI_IMAGE_CACHE environment variable:

export CAPRI_IMAGE_CACHE=/path/to/custom/cache

License

MIT