✨ Features

• 🚀 Auto-optimized — AVIF → WebP → fallback format selection (30-50% smaller)
• 🎯 Zero CLS — Prevents layout shift with aspect ratio
• 📘 Type-safe — Full TypeScript support with strict types
• ⚡ Modern — Svelte 5 runes ($state, $derived, $effect)
• 📱 Responsive — Automatic srcset with configurable DPR support
• 🌐 CDN-ready — Works with Cloudflare, Imgix, or any image CDN
• 🪶 Lightweight — Zero runtime dependencies, tree-shakeable
• ✅ Production-tested — 55 unit tests, 100% type coverage
• 🔒 Secure — XSS-safe with strict input validation

📦 Installation

npm install @7haven/h-image

# Yarn
yarn add @7haven/h-image

# pnpm
pnpm add @7haven/h-image

# Bun
bun add @7haven/h-image

🚀 Quick Start

<script>
    import { Image, configureCdn } from '@7haven/h-image';

    // Optional: Configure your CDN
    configureCdn({ baseUrl: 'https://cdn.example.com' });
</script>

<!-- Auto-optimized: AVIF → WebP → fallback -->
<Image src="file/hero" alt="Hero image" width={1200} aspectRatio="21/9" />

That's it! The component automatically:

• ✅ Generates AVIF and WebP versions
• ✅ Creates responsive srcset
• ✅ Prevents layout shift
• ✅ Lazy loads by default

📖 Usage Examples

Hero Image (LCP Optimization)

<Image
    src="file/hero"
    alt="Hero banner"
    width={1920}
    aspectRatio="21/9"
    fetchpriority="high"
    loading="eager"
/>

Product Grid

<Image
    src="file/product"
    alt="Product thumbnail"
    width={400}
    aspectRatio="1/1"
    transform={{ quality: 85 }}
/>

Art Direction

Different images for different screen sizes:

<Image
    src="file/fallback"
    alt="Responsive hero"
    width={1200}
    sources={[
        { src: 'file/desktop-wide', media: '(min-width: 768px)' },
        { src: 'file/mobile-square', media: '(max-width: 767px)' }
    ]}
/>

Image Transforms

<Image
    src="file/photo"
    alt="Enhanced photo"
    width={800}
    transform={{
        blur: 10,
        brightness: 1.2,
        quality: 90
    }}
/>

⚙️ Props

🎨 Advanced Usage

Custom Sizes Attribute

<Image src="file/hero" alt="Hero" width={1200} sizes="(min-width: 1024px) 50vw, 100vw" />

Object Fit & Position

<Image
    src="file/portrait"
    alt="Person"
    width={400}
    height={400}
    fit="cover"
    position="top center"
/>

Disable Modern Formats

<Image src="file/legacy" alt="Legacy browser support" width={800} modernFormats={false} />

Custom Placeholder

<Image src="file/hero" alt="Hero" width={1200} placeholder="data:image/svg+xml,..." />

💡 Best Practices

Performance

• ✅ Always provide width + height OR aspectRatio to prevent CLS
• ✅ Use fetchpriority="high" + loading="eager" for LCP images only
• ✅ Keep modernFormats={true} (default) for 30-50% smaller file sizes
• ✅ Customize sizes attribute for responsive layouts
• ✅ Use quality: 85 for optimal size/quality balance
• ✅ Component uses CSS contain for rendering performance

Security

• 🔒 XSS-safe URL construction (native URL API)
• 🔒 Strict input validation on all parameters
• 🔒 EXIF metadata automatically stripped by CDN
• 🔒 No script injection vulnerabilities
• 🔒 Type-safe props prevent invalid configurations

Accessibility

• ♿ alt text is required (TypeScript enforced)
• ♿ Semantic HTML (<picture>, <img>)
• ♿ Native keyboard navigation support
• ♿ Screen reader friendly
• ♿ ARIA roles supported via role prop

🔧 Configuration

CDN Setup

import { configureCdn } from '@7haven/h-image';

// Configure once in your root layout
configureCdn({
    baseUrl: 'https://cdn.example.com'
});

Available Transforms

Default Breakpoints

[400, 800, 1200, 1600] + // Standard
    2048; // When zoom={true}

📚 API Reference

Components

import { Image } from '@7haven/h-image';

Configuration

import { configureCdn, getCdnConfig } from '@7haven/h-image';

// Configure CDN
configureCdn({ baseUrl: 'https://cdn.example.com' });

// Get current config
const config = getCdnConfig();

Utilities

import {
    buildImageUrl, // Build CDN URL
    generateSrcset, // Generate srcset string
    generateSizes, // Generate sizes attribute
    calculateHeight, // Calculate height from aspect ratio
    generateBlurPlaceholder // Generate blur placeholder
} from '@7haven/h-image';

Version

import { COMPONENT_VERSION } from '@7haven/h-image';

console.log(COMPONENT_VERSION); // '1.0.0'

TypeScript Types

import type {
    ImageProps, // Component props
    ImageSource, // Source object for art direction
    TransformOptions, // CDN transform options
    ImageFormat, // 'avif' | 'webp' | 'auto'
    FetchPriority, // 'high' | 'low' | 'auto'
    PlaceholderType, // 'blur' | 'none'
    CdnConfig // CDN configuration
} from '@7haven/h-image';

🌐 CDN Compatibility

Works with any CDN that supports image transformations via query parameters:

• ✅ Cloudflare R2 with Image Resizing
• ✅ Imgix
• ✅ Cloudinary
• ✅ Vercel Image Optimization
• ✅ Custom CDN (as long as it supports query params)

// Example: Cloudflare R2
configureCdn({ baseUrl: 'https://cdn.7haven.online' });

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🐛 Report bugs — Open an issue with reproduction steps
2. 💡 Suggest features — Share your ideas for improvements
3. 🔧 Submit PRs — Fix bugs or add features
4. 📖 Improve docs — Help make documentation clearer

📄 License

MIT © 7Haven

🙏 Acknowledgments

Built with:

• Svelte 5 — The reactive framework
• TypeScript — Type safety
• Vitest — Testing framework