import { StorageClient } from '@dcd-sdk/storage-client';
const storage = new StorageClient({
endpoint: 'https://cdn.mycompany.com',
});
// Chain fluent methods:
const avatarUrl = storage
.url('avatars/user-99.jpg')
.width(400)
.height(400)
.crop('fill')
.format('webp')
.quality(85)
.build();
console.log('Optimized CDN URL:', avatarUrl);
// https://cdn.mycompany.com/image/upload/w_400,h_400,c_fill,f_webp,q_85/avatars/user-99.webpThe URL Builder creates transformation strings locally in memory. No HTTP requests are made when calling .build()—it generates the final CDN URL string deterministically using your storage endpoint.
Two Ways to Generate URLs#
1. Fluent Chaining API (Recommended for Developer Ergonomics)
const bannerUrl = storage
.url('banners/summer-promo.png')
.width(1200)
.height(630)
.crop('fill')
.format('webp')
.quality(80)
.build();2. Options Object Syntax (Clean for Reusable Configurations)
You can also pass an options object directly to client.url():
const thumbnailUrl = storage.url('products/sneakers.jpg', {
width: 300,
height: 300,
crop: 'fill',
format: 'webp',
quality: 85,
});Fluent Builder Methods Reference#
| Method | Parameters | Description |
|---|---|---|
.width(w) | number (1 to 4000) | Sets target width in pixels. |
.height(h) | number (1 to 4000) | Sets target height in pixels. |
.resize({ width, height, crop }) | options object | Convenience method to set width, height, and crop mode at once. |
.crop(mode) | 'fill' | 'fit' | 'crop' | 'scale' | Crop strategy. 'fill' crops to fill bounds; 'fit' letterboxes. |
.format(fmt) | 'webp' | 'avif' | 'jpeg' | 'png' | 'auto' | Target format conversion. Use 'auto' for browser format negotiation. |
.quality(q) | number (1 to 100) | Compression quality level (default 80). |
.blur(radius) | number (1 to 100) | Applies Gaussian blur with the specified radius. |
.build() / .to_string() | None | Compiles the chained parameters into the final URL string. |
Getting Untransformed Direct Public URLs#
If you only need the raw asset URL without any resizing or format changes:
const rawUrl = storage.getPublicUrl('avatars/user-99.jpg');
// Output: https://cdn.mycompany.com/image/upload/avatars/user-99.jpgResponsive Images in Modern Frontend (Next.js / HTML5)#
Use the URL builder to generate responsive srcSet attributes effortlessly:
typescript// Generate 1x and 2x Retina image URLs: const img1x = storage.url(publicId).width(400).format('webp').build(); const img2x = storage.url(publicId).width(800).format('webp').build(); const srcSet = `${img1x} 1x, ${img2x} 2x`;
Next Steps#
- Listing & Deleting Files →: Manage files in your storage cluster.
- Direct Browser Uploads →: Upload files directly from user browsers.
- Securing Private Files →: Protect confidential documents.