Skip to content
Astro Image Processor

Astro Image Processor

Astro Image Processor is Astro integration for image optimization and art direction for static build.

GitHub
npm

Features

  • Supports static builds only
    • SSR is not supported and there are no plans to support it
    • Uses the built-in endpoint of the Image Service API (/_image) to display images in the dev server
  • Supports local files, remote files, and Data URLs
  • Includes standard components supporting common use cases
    • <Image> component that outputs an <img> element
      • Automatically switches between foreground mode (placing the element alone) and background mode (placing the element into the container) depending on the presence of the slot
      • Supports art direction via the srcset attribute
    • <Picture> component that outputs a <picture> element
      • Automatically switches between foreground mode (placing the element alone) and background mode (placing the element into the container) depending on the presence of the slot
      • Supports full-spec art direction using <source> elements
      • Supports placeholder animations using the ::after pseudo-element
        • Displays correctly even if JavaScript is disabled (animation is omitted)
    • <Background> component that sets the background-image for the container element
      • Supports art direction using image-set(), nearly equivalent to the <Picture> component
  • Standard components inherit almost all properties of the elements they generate, including Astro-specific properties
    • Supports data-astro-cid-[hash] attributes or .astro-[hash] classes used for scoped styles
  • A custom component using the APIs can handle uncommon use cases
  • Uses sharp for image processing
    • Direct use of a sharp instance, so all sharp functions are available
    • For example, you can crop images with different angles of view from a single high-resolution image
  • Equipped with an independent caching system
    • Shared cache between dev server and static builds
    • Cache deletion policies can use “expiration date” and “whether it was used in the last n builds” (individually or with AND conditions)
    • Possible to sync the cache with a CDN and use it as public files
    • The database for storing cache metadata is configurable (see: Data Adapter)
  • By default, images are output to /dist/_astro/[hash].[ext]
  • Hash algorithm used for generating file and string hashes is configurable (see: Hasher)
  • Outputs HTML compatible with the latest HTML Living Standard
    • <style> and <link> elements are output within the <head> element
  • TypeScript friendly
  • Supports Bun

Considerations for Production Use

For production use, it is strongly recommended to fix the versions of this integration and sharp.

If these implementations are changed, the hashes used for image identification may change. If the hashes change, all caches will need to be rebuilt, and the content of the HTML will also be affected.