or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

advanced.md components.md index.md types.md utilities.md

tile.json

Type Definitions

Complete type definitions for all image data structures, component props, configuration options, and utility function parameters.

Core Types

Image Data Structure

The primary data structure containing all information needed to render an optimized responsive image.

interface IGatsbyImageData {
  /** Image layout strategy */
  layout: Layout;
  /** Display width in pixels */
  width: number;
  /** Display height in pixels */
  height: number;
  /** Background color shown during loading */
  backgroundColor?: string;
  /** Responsive image sources and fallback */
  images: {
    /** Array of responsive image sources */
    sources: Array<{
      /** Responsive srcSet string */
      srcSet: string;
      /** MIME type (e.g., "image/webp") */
      type: string;
      /** Responsive sizes attribute */
      sizes?: string;
    }>;
    /** Fallback image for older browsers */
    fallback: {
      /** Main image source URL */
      src: string;
      /** Responsive srcSet for fallback */
      srcSet: string;
      /** Responsive sizes attribute */
      sizes?: string;
    };
  };
  /** Placeholder shown during loading */
  placeholder?: {
    /** Placeholder image source */
    fallback: string;
  };
}

Layout Types

Layout strategies that determine how images are sized and positioned.

/** 
 * Image layout strategies
 * - fixed: Fixed dimensions, no responsive behavior
 * - constrained: Max-width with responsive scaling
 * - fullWidth: Full container width, maintains aspect ratio
 */
type Layout = "fixed" | "constrained" | "fullWidth";

Image Format Types

Supported image formats for output generation.

/**
 * Supported image formats
 * - jpg: JPEG format
 * - png: PNG format with transparency support
 * - webp: Modern WebP format with better compression
 * - avif: Next-gen AVIF format with superior compression
 * - auto: Automatic format selection based on browser support
 * - "": Default format (usually matches source)
 */
type ImageFormat = "jpg" | "png" | "webp" | "avif" | "auto" | "";

Processing Types

Image processing and transformation options.

/**
 * Image fitting strategies (based on Sharp.js)
 * - cover: Crop to fill dimensions (default)
 * - fill: Stretch to fill dimensions
 * - inside: Resize to fit inside dimensions
 * - outside: Resize to fit outside dimensions
 * - contain: Letterbox to fit dimensions
 */
type Fit = "cover" | "fill" | "inside" | "outside" | "contain";

/**
 * Crop focus points for cover fit strategy
 * Accepts Sharp crop focus values as number or string
 */
type CropFocus = number | string;

Component Props

GatsbyImage Props

Props interface for the GatsbyImage component.

interface GatsbyImageProps {
  /** Alt text for the image (required for accessibility) */
  alt: string;
  /** Image data from GraphQL query (required) */
  image: IGatsbyImageData;
  /** HTML element to render as wrapper (default: 'div') */
  as?: ElementType;
  /** CSS class for the wrapper element */
  className?: string;
  /** CSS class for the img element */
  imgClassName?: string;
  /** Inline styles for the img element */
  imgStyle?: CSSProperties;
  /** Background color shown during loading */
  backgroundColor?: string;
  /** CSS object-fit property for the image */
  objectFit?: CSSProperties["objectFit"];
  /** CSS object-position property for the image */
  objectPosition?: CSSProperties["objectPosition"];
  /** Callback when image finishes loading */
  onLoad?: (event: { wasCached: boolean }) => void;
  /** Callback when image fails to load */
  onError?: ReactEventHandler<HTMLImageElement>;
  /** Callback when image starts loading */
  onStartLoad?: (event: { wasCached: boolean }) => void;
}

StaticImage Props

Props interface for the StaticImage component with build-time processing options.

interface IStaticImageProps extends Omit<GatsbyImageProps, "image"> {
  /** Source URL or path to image file (required) */
  src: string;
  /** Optional filename for processing */
  filename?: string;
  /** Desired width in pixels */
  width?: number;
  /** Desired height in pixels */
  height?: number;
  /** Aspect ratio as width/height */
  aspectRatio?: number;
  /** Image layout strategy */
  layout?: Layout;
  /** Type of placeholder to show during loading */
  placeholder?: PlaceholderType;
  /** Traced SVG options */
  tracedSVGOptions?: Record<string, unknown>;
  /** Output image formats to generate */
  formats?: Array<ImageFormat>;
  /** Image quality from 1-100 */
  quality?: number;
  /** Responsive sizes attribute for the image */
  sizes?: string;
  /** Sharp transformation options */
  transformOptions?: TransformOptions;
  /** JPEG-specific processing options */
  jpgOptions?: Record<string, unknown>;
  /** PNG-specific processing options */
  pngOptions?: Record<string, unknown>;
  /** WebP-specific processing options */
  webpOptions?: Record<string, unknown>;
  /** AVIF-specific processing options */
  avifOptions?: Record<string, unknown>;
  /** Blurred placeholder options */
  blurredOptions?: { width?: number; toFormat?: ImageFormat };
  /** Custom breakpoints for responsive images */
  breakpoints?: Array<number>;
  /** Output pixel densities */
  outputPixelDensities?: Array<number>;
  /** CSS class for the wrapper element */
  className?: string;
  /** CSS class for the img element */
  imgClassName?: string;
  /** Inline styles for the img element */
  imgStyle?: CSSProperties;
  /** Background color shown during loading */
  backgroundColor?: string;
  /** CSS object-fit property for the image */
  objectFit?: CSSProperties["objectFit"];
  /** CSS object-position property for the image */
  objectPosition?: CSSProperties["objectPosition"];
  /** Callback when image finishes loading */
  onLoad?: (event: { wasCached: boolean }) => void;
  /** Callback when image fails to load */
  onError?: ReactEventHandler<HTMLImageElement>;
  /** Callback when image starts loading */
  onStartLoad?: (event: { wasCached: boolean }) => void;
}

/**
 * Placeholder types for loading states
 * - tracedSVG: Simplified SVG trace of the image
 * - dominantColor: Solid color extracted from the image
 * - blurred: Low-resolution blurred version
 * - none: No placeholder
 */
type PlaceholderType = "tracedSVG" | "dominantColor" | "blurred" | "none";

Processing Options

Detailed configuration interfaces for image processing.

interface TransformOptions {
  /** How to crop/resize the image */
  fit?: Fit;
  /** Crop focus point */
  cropFocus?: number | string;
  /** Duotone effect configuration */
  duotone?: {
    highlight: string;
    shadow: string;
    opacity?: number;
  };
  /** Convert to grayscale */
  grayscale?: boolean;
  /** Rotate image in degrees */
  rotate?: number;
  /** Trim border pixels */
  trim?: number;
}

interface JPGOptions {
  /** JPEG quality from 1-100 */
  quality?: number;
  /** Use progressive JPEG encoding */
  progressive?: boolean;
  /** Chroma subsampling method */
  chromaSubsampling?: "4:2:0" | "4:4:4";
}

interface PNGOptions {
  /** PNG quality from 1-100 */
  quality?: number;
  /** Compression speed vs size (1-10) */
  compressionSpeed?: number;
  /** Use palette-based PNG */
  palette?: boolean;
  /** PNG compression level (0-9) */
  compressionLevel?: number;
}

interface WebPOptions {
  /** WebP quality from 1-100 */
  quality?: number;
  /** Use lossless WebP encoding */
  lossless?: boolean;
  /** Enable near-lossless encoding */
  nearLossless?: boolean;
}

interface AVIFOptions {
  /** AVIF quality from 1-100 */
  quality?: number;
  /** Encoding speed from 1-10 (slower = better compression) */
  speed?: number;
  /** Use lossless AVIF encoding */
  lossless?: boolean;
  /** Chroma subsampling for AVIF */
  chromaSubsampling?: "4:2:0" | "4:4:4";
}

Utility Function Types

Image Data Extraction

Types for utility functions that extract image data from various sources.

/**
 * Union type for various GraphQL node types containing image data
 */
type ImageDataLike =
  | IGatsbyImageData
  | IGatsbyImageDataParent
  | IGatsbyImageParent
  | FileNode
  | null
  | undefined;

/** GraphQL node with gatsbyImageData field */
interface IGatsbyImageDataParent {
  gatsbyImageData: IGatsbyImageData;
}

/** GraphQL node with legacy gatsbyImage field */
interface IGatsbyImageParent {
  gatsbyImage: IGatsbyImageData;
}

/** File node from gatsby-source-filesystem */
interface FileNode {
  childImageSharp?: {
    gatsbyImageData?: IGatsbyImageData;
    gatsbyImage?: IGatsbyImageData;
  };
}

External Service Integration

Types for integrating with external image services and CDNs.

interface IGetImageDataArgs<OptionsType = Record<string, unknown>> {
  /** Base URL for the image service */
  baseUrl: string;
  /** Function to generate URLs based on dimensions and format */
  urlBuilder: (args: IUrlBuilderArgs<OptionsType>) => string;
  /** Desired image width */
  width?: number;
  /** Desired image height */
  height?: number;
  /** Original image width (for aspect ratio calculation) */
  sourceWidth?: number;
  /** Original image height (for aspect ratio calculation) */
  sourceHeight?: number;
  /** Image layout strategy */
  layout?: Layout;
  /** Output image formats */
  formats?: Array<ImageFormat>;
  /** Custom breakpoints for responsive images */
  breakpoints?: Array<number>;
  /** Additional options passed to urlBuilder */
  options?: OptionsType;
  /** Placeholder image URL */
  placeholderURL?: string;
  /** Background color */
  backgroundColor?: string;
}

interface IUrlBuilderArgs<OptionsType = Record<string, unknown>> {
  /** Target image width */
  width: number;
  /** Target image height */
  height: number;
  /** Base URL for the image */
  baseUrl: string;
  /** Image format */
  format: ImageFormat;
  /** Additional service-specific options */
  options: OptionsType;
}

/**
 * URL builder function type for external services
 */
type UrlBuilder<OptionsType = Record<string, unknown>> = (
  args: IUrlBuilderArgs<OptionsType>
) => string;

Art Direction

Types for art-directed responsive images.

interface IArtDirectedImage {
  /** CSS media query string (e.g., "(max-width: 768px)") */
  media: string;
  /** Image to display when media query matches */
  image: IGatsbyImageData;
}

Internal Processing

Types used internally for image generation and processing.

interface IGatsbyImageHelperArgs {
  /** Plugin name for error reporting */
  pluginName: string;
  /** Function to generate individual image sources */
  generateImageSource: (
    filename: string,
    width: number,
    height: number,
    format: ImageFormat,
    fit?: Fit,
    options?: Record<string, unknown>
  ) => IImage;
  /** Image layout strategy */
  layout?: Layout;
  /** Output image formats */
  formats?: Array<ImageFormat>;
  /** Filename for processing */
  filename: string;
  /** Placeholder image URL */
  placeholderURL?: string;
  /** Target image width */
  width?: number;
  /** Target image height */
  height?: number;
  /** Responsive sizes attribute */
  sizes?: string;
  /** Reporter for warnings */
  reporter?: { warn(message: string): void };
  /** Original image metadata */
  sourceMetadata?: { width: number; height: number; format: ImageFormat };
  /** Image fit strategy */
  fit?: Fit;
  /** Processing options */
  options?: Record<string, unknown>;
  /** Custom breakpoints */
  breakpoints?: Array<number>;
  /** Background color */
  backgroundColor?: string;
  /** Aspect ratio */
  aspectRatio?: number;
}

interface ISharpGatsbyImageArgs extends IGatsbyImageHelperArgs {
  /** Sharp transformation options */
  transformOptions?: TransformOptions;
  /** JPEG processing options */
  jpgOptions?: JPGOptions;
  /** PNG processing options */
  pngOptions?: PNGOptions;
  /** WebP processing options */
  webpOptions?: WebPOptions;
  /** AVIF processing options */
  avifOptions?: AVIFOptions;
}

interface IImage {
  /** Image source URL */
  src: string;
  /** Image width in pixels */
  width: number;
  /** Image height in pixels */
  height: number;
}

Component Internal Types

Picture Component

Types for the internal Picture component used by image components.

interface PictureProps {
  /** Array of responsive image sources */
  sources: Array<{
    srcSet: string;
    type: string;
    sizes?: string;
  }>;
  /** Fallback image data */
  fallback: {
    src: string;
    srcSet: string;
    sizes?: string;
  };
  /** Image alt text */
  alt: string;
  /** CSS class for the img element */
  className?: string;
  /** Inline styles for the img element */
  style?: CSSProperties;
  /** Loading strategy */
  loading?: "lazy" | "eager";
  /** Decoding hint */
  decoding?: "async" | "sync" | "auto";
}

Placeholder Component

Types for the Placeholder component.

interface PlaceholderProps {
  /** Placeholder image URL */
  fallback?: string;
  /** Responsive sources for placeholder */
  sources?: Array<{
    srcSet: string;
    type: string;
    sizes?: string;
  }>;
  /** CSS class for placeholder element */
  className?: string;
  /** Inline styles for placeholder */
  style?: CSSProperties;
}

Type Usage Examples

Custom Service Integration

// Example: Custom CDN with typed options
interface CustomCDNOptions {
  crop?: "center" | "smart" | "face";
  quality?: number;
  effects?: Array<"blur" | "grayscale" | "sepia">;
}

const createCustomCDNImage = (
  imageId: string,
  options: CustomCDNOptions = {}
): IGatsbyImageData => {
  return getImageData<CustomCDNOptions>({
    baseUrl: `https://cdn.example.com/${imageId}`,
    urlBuilder: ({ width, height, format, options }) => {
      // Type-safe access to custom options
      const params = {
        w: width,
        h: height,
        f: format,
        crop: options.crop,
        q: options.quality,
        effects: options.effects?.join(","),
      };
      // ... build URL
    },
    options,
    width: 800,
    height: 600,
  });
};

Type Guards

// Type guard for checking image data
const isGatsbyImageData = (data: unknown): data is IGatsbyImageData => {
  return (
    typeof data === "object" &&
    data !== null &&
    "layout" in data &&
    "width" in data &&
    "height" in data &&
    "images" in data
  );
};

// Usage in components
const SafeImage = ({ imageData }: { imageData: unknown }) => {
  if (!isGatsbyImageData(imageData)) {
    return <div>Invalid image data</div>;
  }

  return <GatsbyImage image={imageData} alt="Safe image" />;
};