@flightdev/image

Image optimization package for Flight Framework with Sharp, Squoosh, and CDN adapters.

Installation

npm install @flightdev/image

# Install your preferred processor:
npm install sharp           # For Node.js (fastest)
# OR use CDN adapters (no additional install needed)

Quick Start

import { createImage } from '@flightdev/image';
import { sharp } from '@flightdev/image/sharp';

const image = createImage(sharp());

// Optimize an image
const result = await image.optimize('./hero.jpg', {
  width: 800,
  format: 'webp',
  quality: 80,
});

// Generate blur placeholder
const blur = await image.blur('./hero.jpg');

// Generate responsive variants
const responsive = await image.responsive('./hero.jpg', {
  widths: [640, 768, 1024, 1280],
  formats: ['webp', 'avif'],
});

Adapters

Sharp (Node.js)

Fastest option for Node.js environments.

import { sharp } from '@flightdev/image/sharp';

const adapter = sharp({
  cache: true,        // Enable internal cache
  concurrency: 4,     // Parallel processing
  simd: true,         // SIMD optimization
});

Squoosh (Edge/WASM)

Works on Edge runtimes (Cloudflare Workers, Vercel Edge).

import { squoosh } from '@flightdev/image/squoosh';

const adapter = squoosh();

Cloudinary (CDN)

CDN-based optimization, no local processing.

import { cloudinary } from '@flightdev/image/cloudinary';

const adapter = cloudinary({
  cloudName: 'my-cloud',
  apiKey: process.env.CLOUDINARY_API_KEY,
  apiSecret: process.env.CLOUDINARY_API_SECRET,
});

Imgix (CDN)

import { imgix } from '@flightdev/image/imgix';

const adapter = imgix({
  domain: 'my-source.imgix.net',
  secureUrlToken: process.env.IMGIX_TOKEN,
});

UI Components

React

import { Image } from '@flightdev/image/react';

<Image
  src="/hero.jpg"
  alt="Hero image"
  width={800}
  height={600}
  priority           // Preload for LCP
  placeholder="blur" // Show blur while loading
  blurDataUrl={blur} // From image.blur()
/>

Vue

<script setup>
import { FlightImage } from '@flightdev/image/vue';
</script>

<template>
  <FlightImage
    src="/hero.jpg"
    alt="Hero"
    :width="800"
    :height="600"
    priority
    placeholder="blur"
  />
</template>

Svelte

<script>
  import { createImageProps, lazyImage } from '@flightdev/image/svelte';
  
  const props = createImageProps({
    src: '/hero.jpg',
    alt: 'Hero',
    width: 800,
    height: 600,
  });
</script>

<img {...props} use:lazyImage={blurDataUrl} />

Solid

import { Image } from '@flightdev/image/solid';

<Image
  src="/hero.jpg"
  alt="Hero"
  width={800}
  height={600}
  priority
  placeholder="blur"
/>

API Reference

ImageOptimizeOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | width | number | - | Target width | | height | number | - | Target height | | format | ImageFormat | 'auto' | Output format | | quality | number | 80 | Quality (1-100) | | fit | ImageFit | 'cover' | Resize fit mode | | blur | boolean | false | Generate blur placeholder | | withoutEnlargement | boolean | false | Prevent upscaling | | preserveMetadata | boolean | false | Keep EXIF data |

ImageFormat

'jpeg' | 'png' | 'webp' | 'avif' | 'gif' | 'tiff' | 'auto'

ImageFit

'cover' | 'contain' | 'fill' | 'inside' | 'outside'

Creating Custom Adapters

Implement the ImageAdapter interface:

import type { ImageAdapter } from '@flightdev/image';

export function myAdapter(config: MyConfig): ImageAdapter {
  return {
    name: 'my-adapter',
    
    supportsFormat(format) {
      return ['webp', 'jpeg', 'png'].includes(format);
    },
    
    async getMetadata(input) {
      // Return image dimensions, format, etc.
    },
    
    async optimize(input, options) {
      // Process and return optimized image
    },
    
    async generateBlurPlaceholder(input, size) {
      // Return base64 blur placeholder
    },
    
    async generateResponsive(input, config) {
      // Generate multiple sizes
    },
  };
}

License

MIT