A comprehensive Cloudflare Worker for image transformation with enterprise-grade features, built on a service-oriented architecture.
Image Resizer 2 provides a high-performance, feature-rich image transformation service that leverages Cloudflare's Image Resizing capabilities while adding:
- Multiple storage backends with parallel fetching
- Multi-layer caching with intelligent cache management
- Advanced client detection for optimized delivery
- Comprehensive debugging and monitoring tools
- Extensive customization options
graph TD
A[Client Browser] -->|Image Request| B[Cloudflare Worker]
B -->|Parse Request| C[Path Analyzer]
C -->|Extract Parameters| D[Transform Options Builder]
B -->|Check Storage Priority| E{Storage Priority}
E -->|R2 First| F[R2 Storage]
E -->|Remote First| G[Remote URL]
E -->|Fallback| H[Fallback URL]
F -->|Fetch Image| I[Image Transformer]
G -->|Authentication| J[Auth Service]
J -->|Authenticated Request| I
H -->|Fetch Image| I
I -->|Apply Transformations| K[Cache]
K -->|Return Image| A
graph TD
A[Image Handler] --> B[Service Container]
B --> C[Storage Service]
B --> D[Transformation Service]
B --> E[Cache Service]
B --> F[Client Detection Service]
B --> G[Debug Service]
B --> H[Auth Service]
B --> I[Metadata Service]
B --> J[Configuration Service]
B --> K[Logging Service]
C --> L[R2 Storage]
C --> M[Remote Storage]
C --> N[Fallback Storage]
E --> O[Cache Tags Manager]
E --> P[TTL Calculator]
E --> Q[Cache Performance Manager]
E --> R[KV Transform Cache]
- Image Transformation: Resize, crop, format conversion, quality adjustment, and effects
- Multiple Storage Options: R2, remote URLs, and fallbacks with priority-based parallel fetching
- Responsive Images: Auto-optimization based on client hints and device detection
- Smart Transformations: Automated cropping, aspect ratio handling, and focal point detection
- Service-Oriented Architecture: Modular design with clean interfaces and lazy initialization
- Multi-Layer Caching: Tiered caching strategy with intelligent TTL calculations and cache tags
- KV Transform Cache: Persistent storage for transformed images with purging capabilities
- Authenticated Origins: Support for secure image sources with multiple auth strategies
- Akamai Compatibility: Seamless migration path from Akamai Image Manager with parameter translation
- Path Templates: URL-based transformation templates for consistent image presentation
- Path Transformations: Storage-specific path mapping for flexible directory structures
- Comprehensive Logging: Multi-level logging with structured output and breadcrumb tracing
- Debug Tools: Interactive debug reports, detailed headers, and visualization tools
- Performance Optimization: Optimized services with parallel operations and efficient resource usage
- Error Handling: Structured error system with detailed context and appropriate status codes
- Centralized Configuration: Unified configuration with environment-specific settings
https://your-worker.com/image.jpg?width=800&height=600&fit=cover
https://your-worker.com/image.jpg?r=16:9&p=0.5,0.3&f=l
Where:
r=16:9sets a 16:9 aspect ratiop=0.5,0.3defines the focal point (center of the image)f=luses the large size preset (750px width)
https://your-worker.com/_width=800/_format=webp/image.jpg
https://your-worker.com/thumbnail/image.jpg
https://your-worker.com/og-image/image.jpg
https://your-worker.com/image.jpg?smart=true&aspect=1:1&width=400
https://your-worker.com/image.jpg?im.resize=width:400,height:300,mode:fit
- Node.js (version 18 or later)
- Wrangler CLI (version 4.2.0 or later)
- Clone this repository
- Install dependencies:
npm install- Configure your storage options in
wrangler.jsonc - Start the development server:
npm run devDeploy to different environments:
# Development
npm run deploy:dev
# Staging
npm run deploy:staging
# Production
npm run deploy:prodThe Image Resizer can be configured through:
- wrangler.jsonc: Main configuration file with environment-specific settings
- Environment Variables: Override specific settings via environment variables
- Configuration API: Dynamically update configuration via the API (when enabled)
See the Configuration Guide for detailed options.
Our documentation has been completely reorganized and updated to provide comprehensive information for both users and developers.
- Introduction - Overview and getting started
- Core - Architecture, setup, and core concepts
- Configuration - Configuring the service
- Features - Detailed feature documentation
- Caching - Comprehensive caching guide
- Storage - Storage options and configuration
- Integrations - Third-party integrations
- Debugging - Debugging and monitoring
- Architecture - Architectural decisions and patterns
- Development - Development guidelines and implementation details
- Performance - Performance optimization guide
- Error Handling - Error system documentation
- Testing - Testing strategy and guidelines
Use our Documentation Navigation for a complete overview of all documentation.
The Image Resizer follows a service-oriented architecture:
src/index.ts- Main entry point and request handlersrc/services/- Core service implementationssrc/domain/- Domain logic and commandssrc/errors/- Error type definitionssrc/handlers/- Request handlers for different endpointssrc/parameters/- Parameter parsing and processingsrc/utils/- Utility functions and helperstest/- Test suitedocs/- Documentationconfig/- Configuration examples and modules
See CONTRIBUTING.md for details on how to contribute to this project.
MIT License