Image Builder

A lightweight utility for building Base64 encoded image transformation URLs for Sharp.

📦 Installation

npm install sharp-image-url-builder

🚀 Usage

import { ImageUrlBuilder } from 'sharp-image-url-builder';

const builder = new ImageUrlBuilder('https://cdn.example.com', 'my-bucket');

const url = builder
  .setKey('images/photo.jpg')
  .resize({
    width: 800,
    height: 600,
    fit: 'cover',
    position: 'center'
  })
  .blur(5)
  .toURL();

console.log(url);
// https://cdn.example.com/eyJidWNrZXQiOiJteS1idWNrZXQiLCJrZXkiOiJpbWFnZXMvcGhvdG8uanBnIiwiZWRpdHMiOnsicmVzaXplIjp7IndpZHRoIjo4MDAsImhlaWdodCI6NjAwLCJmaXQiOiJjb3ZlciIsInBvc2l0aW9uIjoiY2VudGVyIn0sImJsdXIiOjV9fQ==

🔧 API

new ImageUrlBuilder(baseUrl: string, bucket: string)

Create a new builder instance.

• baseUrl – your CDN or image service base URL
• bucket – bucket/container name

.setKey(key: string): this

Set the image key (path to your file in the bucket).

.resize(resize: Resize): this

Apply resize options.

builder.resize({
  width: 400,
  height: 300,
  fit: 'contain',
  position: 'top',
  gravity: 'north-west',
  withoutEnlargement: true
});

Resize Options

• width?: number
• height?: number
• fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
• position?: 'top' | 'bottom' | 'left' | 'right' | 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
• gravity?: 'north' | 'south' | 'east' | 'west' | 'center' | 'north-east' | 'north-west' | 'south-east' | 'south-west'
• entropy?: 'entropy' | 'attention'
• withoutEnlargement?: boolean

.blur(amount: number): this

Apply a blur effect.

.toURL(): string

Generate the final transformation URL. Encodes the transformObject as Base64 JSON.

🛠 Use Cases

• Generate Base64 encoded URLs for serverless image transformers
• Apply simple effects (blur, crop) without heavy backend logic