Image Processor

The @ecopages/image-processor package provides powerful image processing capabilities for transforming and optimizing images for web use in your Ecopages project.

Installation

Install the package from JSR:

bunx jsr add @ecopages/image-processor

Configuration

Add the image processor to your Ecopages configuration:

import path from 'node:path';
import { ConfigBuilder } from '@ecopages/core';
import { ImageProcessorPlugin } from '@ecopages/image-processor';
 
const imageProcessor = new ImageProcessorPlugin({
	name: 'ecopages-image-processor',
	type: 'image',
	options: {
		sourceDir: path.resolve(import.meta.dir, 'src/images'),
		outputDir: path.resolve(import.meta.dir, '.eco/images'),
		publicPath: '/images',
		acceptedFormats: ['jpg', 'jpeg', 'png', 'webp'],
		quality: 80,
		format: 'webp',
		sizes: [
			{ width: 320, label: 'sm' },
			{ width: 768, label: 'md' },
			{ width: 1024, label: 'lg' },
			{ width: 1920, label: 'xl' },
		],
	},
});
 
export default await new ConfigBuilder()
	.setRootDir(import.meta.dir)
	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
	.setProcessors([imageProcessor])
	.build();

Configuration Options

sourceDir: Directory containing your source images
outputDir: Where processed images will be saved
publicPath: Public URL path for accessing images
acceptedFormats: Array of input image formats to process
quality: Output image quality (1-100)
format: Default output format
sizes: Array of responsive image sizes to generate

Package Structure

The image processor provides several entry points:

Main processor: @ecopages/image-processor
Type definitions: @ecopages/image-processor/types
HTML Component: @ecopages/image-processor/component/html
React Component: @ecopages/image-processor/component/react

Components Usage

HTML Component

import { Image } from '@ecopages/image-processor/component/html';
 
const imageHtml = Image({
	src: '/images/hero.jpg',
	alt: 'Hero image',
	width: 800,
	height: 600,
	loading: 'lazy',
});

React Component

import { Image } from '@ecopages/image-processor/component/react';
 
function MyComponent() {
	return (
		<Image src="/images/hero.jpg" alt="Hero image" width={800} height={600} loading="lazy" />
	);
}

The ecopages:images virtual module provides a unified, type-safe way to handle images across your project:

// All images from your source directory are available as named exports
import { heroImage, profilePicture, blogThumbnail } from "ecopages:images";
 
// Names are automatically converted to camelCase
// example:
// src/images/hero-image.jpg -> heroImage
// src/images/profile_picture.png -> profilePicture

Benefits:

TypeScript Integration: Full autocompletion support for image names
Automatic Processing: Images are processed at build time
Tree Shaking: Only imported images and their required metadata are included in the final bundle
Type Safety: Prevents imports of non-existent images
Unified API: Consistent way to handle images across your project

Dependencies

The image processor uses:

sharp for high-performance image processing
React 19 for the React component integration
@ecopages/logger for logging

Examples

import { EcoImage } from '@ecopages/image-processor/component/html';
import { janKoprivaNex3P5IbnpgUnsplashJpg } from 'ecopages:images';
 
<div class="grid gap-8">
	<EcoImage
		{...janKoprivaNex3P5IbnpgUnsplashJpg}
		alt="green plant on persons hand"
		layout="full-width"
		height={200}
	/>
	<EcoImage
		{...janKoprivaNex3P5IbnpgUnsplashJpg}
		alt="green plant on persons hand"
		width={600}
		height={200}
		layout="constrained"
	/>
	<EcoImage
		{...janKoprivaNex3P5IbnpgUnsplashJpg}
		alt="green plant on persons hand"
		layout="fixed"
		width={200}
		height={200}
	/>
</div>

import { EcoImage } from '@ecopages/image-processor/component/html';
import { janKoprivaNex3P5IbnpgUnsplashJpg } from 'ecopages:images';
 
<div class="grid gap-8">
	<EcoImage
		{...janKoprivaNex3P5IbnpgUnsplashJpg}
		width={400}
		alt="green plant on persons hand"
		priority={true}
		unstyled={true}
		data-test="attribute"
	/>
	<EcoImage
		{...janKoprivaNex3P5IbnpgUnsplashJpg}
		alt="green plant on persons hand"
		width={300}
		aspectRatio="1/2"
	/>
</div>

Photo by Jan Kopřiva on Unsplash