@itoshinji/media-core

The framework-independent, low-level public API for the media delivery service.

This package provides the shared URL format, image versions, responsive presets, output formats, types, and validation helpers used by the media Worker, admin application, and framework integrations such as @itoshinji/media-astro.

It has no runtime dependency on Cloudflare, Astro, React, or Valibot.

Installation

pnpm add @itoshinji/media-core

Astro applications that only render images should install @itoshinji/media-astro instead. Install this package directly when you need to construct or parse image paths, validate hashes, or inspect image presets and formats outside the component.

Usage

import { CURRENT_IMAGE_VERSION, createImagePath, type ImageHash } from "@itoshinji/media-core";

const hash = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" as ImageHash;

const path = createImagePath({
  version: CURRENT_IMAGE_VERSION,
  hash,
  preset: "w640",
  format: "avif",
});

// /images/v1/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef-w640.avif

The current image version is used when version is omitted.

@itoshinji/media-astro does not re-export this package. Add @itoshinji/media-core to your own dependencies whenever you import from it directly, even if it is already installed transitively.

Version behavior

Image versions identify immutable transformation outputs. The media Worker may serve an older version while its derived object remains in R2, but it only generates missing images for the current version.

Package format

The published package contains compiled ESM and TypeScript declarations under dist/. Consumers never execute TypeScript source from node_modules.