A modern, composable image processing library for JavaScript and TypeScript that provides a type-safe builder API for image transformations.
npm install pixlyA modern, composable image processing library for JavaScript and TypeScript that provides a type-safe builder API for image transformations.
``bash`
npm install pixlyor
yarn add pixlyor
bun add pixly
`typescript
import { px } from 'pixly';
// Process an image with auto-detection
const result = await px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 80 }))
.apply(px.resize({ width: 800 }))
.process('path/to/image.jpg');
// Get the result as different formats
const buffer = result.toBuffer();
const blob = result.toBlob();
const dataUrl = result.toDataURL();
`
Pixly uses a fluent builder pattern that guides you through the image processing pipeline:
1. Set a decoder (to read the input format)
2. Set an encoder (to write the output format)
3. Apply transformations
4. Process the input
`typescript`
const result = await px.decoder(px.jpeg.decode()) // 1. Decode JPEG
.encoder(px.png.encode()) // 2. Encode to PNG
.apply(px.resize({ width: 500 })) // 3. Add operations
.apply(px.rotate(90)) // 3. Chain more operations
.process(imageInput); // 4. Process
The API uses TypeScript to ensure correct usage:
- decoder() and encoder() must be called before process()
- Each can only be called once
- Operations are type-checked
Pixly accepts various input types:
`typescript
// From URL
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.process('https://example.com/image.jpg');
// From File (browser)
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.process(fileInput.files[0]);
// From Buffer/ArrayBuffer
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.process(arrayBuffer);
// From Blob
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.process(blob);
`
Each codec provides both decode() and encode() methods:
- PNG: px.pngpx.jpeg
- JPEG: px.webp
- WebP: px.avif
- AVIF: px.jxl
- JPEG XL: px.qoi
- QOI: px.auto
- Auto: (decode only - auto-detects format)
`typescript
// Convert PNG to JPEG
const result = await px.decoder(px.png.decode())
.encoder(px.jpeg.encode({ quality: 90 }))
.process(pngImage);
// Convert any format to WebP
const result = await px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 85, lossless: false }))
.process(inputImage);
`
Different codecs support different encoding options:
`typescript
// JPEG options
px.jpeg.encode({ quality: 90 });
// WebP options
px.webp.encode({ quality: 85, lossless: false });
// PNG options
px.png.encode({ compressionLevel: 6 });
`
All operations are applied using the apply() method:
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.apply(px.resize({
width: 800,
height: 600,
fit: 'cover', // 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
position: 'center', // Position when cropping
background: [255, 255, 255, 0] // RGBA background color
}))
.process(input);
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.jpeg.encode())
.apply(px.rotate(90)) // Rotate 90 degrees clockwise
.process(input);
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.png.encode())
.apply(px.flip('horizontal')) // 'horizontal' or 'vertical'
.process(input);
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.apply(px.crop({
x: 100,
y: 100,
width: 400,
height: 300
}))
.process(input);
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.jpeg.encode())
.apply(px.blur(5)) // Blur radius
.process(input);
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.jpeg.encode())
.apply(px.sharpen(1.5)) // Sharpen amount
.process(input);
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.jpeg.encode())
.apply(px.brightness(1.2)) // 1.0 = no change, >1 = brighter, <1 = darker
.process(input);
Operations can be chained to create complex transformations:
`typescript`
const result = await px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 80 }))
.apply(px.resize({ width: 1200, height: 800, fit: 'cover' }))
.apply(px.rotate(45))
.apply(px.brightness(1.1))
.apply(px.sharpen(1.2))
.apply(px.blur(0.5))
.process(input);
Create reusable operation chains:
`typescript
// Create a preset (without encoder/decoder)
const thumbnailPreset = px
.apply(px.resize({ width: 150, height: 150, fit: 'cover' }))
.apply(px.sharpen(1.2))
.preset();
const instagramPreset = px
.apply(px.resize({ width: 1080, height: 1080, fit: 'cover' }))
.apply(px.brightness(1.05))
.apply(px.sharpen(1.1))
.preset();
// Use presets in different contexts
const thumbnail = await px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 80 }))
.apply(thumbnailPreset)
.process(input);
const instagramPost = await px.decoder(px.auto())
.encoder(px.jpeg.encode({ quality: 90 }))
.apply(instagramPreset)
.process(input);
`
The processing result provides multiple output methods:
`typescript
const result = await px.decoder(px.auto())
.encoder(px.webp.encode())
.apply(px.resize({ width: 800 }))
.process(input);
// Get as Uint8Array buffer
const buffer = result.toBuffer();
// Get as Blob (useful in browsers)
const blob = result.toBlob();
// Get as data URL (base64 encoded)
const dataUrl = result.toDataURL();
`
Pixly provides clear error messages for common issues:
`typescript`
try {
// This will throw - decoder and encoder required
const result = await px
.apply(px.resize({ width: 100 }))
.process(input);
} catch (error) {
console.error('Processing failed:', error.message);
}
Pixly is written in TypeScript and provides full type safety:
`typescript`
import type {
ImageEditor,
ProcessingResult,
ResizeOptions,
ImageInput
} from 'pixly';
`typescript
const sizes = [
{ width: 150, name: 'thumbnail' },
{ width: 800, name: 'medium' },
{ width: 1920, name: 'large' }
];
const results = await Promise.all(
sizes.map(async ({ width, name }) => {
const result = await px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 85 }))
.apply(px.resize({ width }))
.process(originalImage);
return {
name,
blob: result.toBlob()
};
})
);
`
`typescript
// Create a web optimization preset
const webOptimized = px
.apply(px.resize({ width: 1920, height: 1080, fit: 'inside' }))
.apply(px.sharpen(1.1))
.preset();
// Apply to multiple images
const processedImages = await Promise.all(
imageFiles.map(file =>
px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 85 }))
.apply(webOptimized)
.process(file)
)
);
`
`typescript`
// Convert all images to modern formats
async function modernizeImage(input: ImageInput) {
// Try AVIF first (best compression)
try {
return await px.decoder(px.auto())
.encoder(px.avif.encode({ quality: 80 }))
.process(input);
} catch {
// Fall back to WebP
return await px.decoder(px.auto())
.encoder(px.webp.encode({ quality: 85 }))
.process(input);
}
}
`typescript
const profilePicturePreset = px
.apply(px.resize({ width: 400, height: 400, fit: 'cover' }))
.apply(px.sharpen(1.2))
.preset();
async function generateProfilePicture(file: File) {
const result = await px.decoder(px.auto())
.encoder(px.jpeg.encode({ quality: 90 }))
.apply(profilePicturePreset)
.process(file);
return result.toBlob();
}
`
Pixly works in both browser and Node.js environments, automatically handling environment-specific features.
1. Reuse Presets: Create presets once and reuse them for consistent transformations
2. Choose Appropriate Formats: Use WebP or AVIF for smaller file sizes, JPEG for photos, PNG for images with transparency
3. Optimize Quality Settings: Balance quality and file size based on your use case
4. Process in Parallel: Use Promise.all()` for batch processing
MIT