severmedia
v1.0.4
Published
Cloudinary alternative SDK for Sever Media image optimization, transformation, and storage.
Maintainers
Readme
severmedia ⚡
High-performance Cloudinary alternative SDK for Sever Media. Real-time image transformations, dynamic resizing, format conversion, filters, React components, custom hooks, and file storage.
📦 Installation
npm install severmedia
# or
yarn add severmedia
# or
pnpm add severmedia⚙️ Environment Setup
Add these configuration variables to your project's .env or .env.local file:
# All secret keys (MinIO Access Keys & Imgproxy Salt) stay safe on Sever Media platform.
# Client apps only need the Server URL and an API Key generated from Dashboard!
NEXT_PUBLIC_SEVER_MEDIA_SERVER_URL=https://img.stuhal.cloud
NEXT_PUBLIC_SEVER_MEDIA_API_KEY=sk_live_your_generated_api_keyOr configure programmatically in your code:
import { configure } from 'severmedia';
configure({
serverUrl: 'https://img.stuhal.cloud',
apiKey: 'sk_live_your_generated_api_key',
});🎨 Feature Showcase & Examples
Below are practical examples for every feature using the <Image /> component, image() builder API, and storage hooks.
1. Resizing & Fitting Modes
Control output dimensions and aspect ratio handling using fit.
import { Image } from 'severmedia';
// 1. Exact dimensions (Cover mode)
<Image src="demo/landscape.jpg" width={400} height={300} fit="cover" alt="Cover fit" />
// 2. Contain within bounds (Preserve aspect ratio)
<Image src="demo/landscape.jpg" width={400} height={300} fit="contain" alt="Contain fit" />
// 3. Fill bounds (Crop overflow)
<Image src="demo/landscape.jpg" width={400} height={300} fit="fill" alt="Fill fit" />
// 4. Force exact aspect stretch
<Image src="demo/landscape.jpg" width={400} height={200} fit="force" alt="Force stretch" />2. Format Conversion (Next-Gen Formats)
Automatically convert images to lightweight WebP or AVIF formats.
import { Image } from 'severmedia';
// Convert to WebP (Recommended)
<Image src="demo/photo.jpg" width={600} format="webp" alt="WebP format" />
// Convert to AVIF (Ultra small file size)
<Image src="demo/photo.jpg" width={600} format="avif" alt="AVIF format" />
// Convert to PNG (Transparent assets)
<Image src="demo/icon.jpg" width={200} format="png" alt="PNG format" />
// Auto-select best format supported by user browser
<Image src="demo/photo.jpg" width={600} format="auto" alt="Auto format" />3. Compression & Quality Control
Optimize payload size by adjusting the quality prop (1–100).
import { Image } from 'severmedia';
// High quality (E-Commerce Product Detail)
<Image src="products/shoe.jpg" width={800} quality={90} alt="Product Detail" />
// Standard web quality (Default: 85)
<Image src="products/shoe.jpg" width={400} quality={85} alt="Product Card" />
// Low quality / High compression (Thumbnails)
<Image src="products/shoe.jpg" width={150} quality={50} alt="Thumbnail" />4. Smart Cropping & Gravity Alignment
Focus on specific regions or use AI smart detection (crop="smart").
import { Image } from 'severmedia';
// Center Crop
<Image src="people/portrait.jpg" width={300} height={300} crop="center" alt="Center" />
// Top Crop (Heads & Portraits)
<Image src="people/portrait.jpg" width={300} height={300} crop="top" alt="Top" />
// Bottom Crop
<Image src="people/portrait.jpg" width={300} height={300} crop="bottom" alt="Bottom" />
// Smart AI Crop (Detects subject)
<Image src="people/portrait.jpg" width={300} height={300} crop="smart" alt="Smart AI" />5. Visual Filters & Effects (Blur, Sharpen, Pixelate)
Apply server-side real-time image processing filters.
import { Image } from 'severmedia';
// Blur Effect (Useful for placeholders & backgrounds)
<Image src="demo/nature.jpg" width={500} blur={10} alt="Blurred" />
// Sharpening (Enhance fine details)
<Image src="demo/nature.jpg" width={500} sharpen={3} alt="Sharpened" />
// Pixelate / Censorship Effect
<Image src="demo/nature.jpg" width={500} pixelate={12} alt="Pixelated" />6. Rotation & Flipping
Rotate or flip images directly on the server without client-side canvas.
import { Image } from 'severmedia';
// Rotate 90 degrees clockwise
<Image src="demo/document.jpg" width={400} rotate={90} alt="Rotate 90" />
// Horizontal Flip (Mirror effect)
<Image src="demo/avatar.jpg" width={200} flip="horizontal" alt="Horizontal Flip" />
// Vertical Flip
<Image src="demo/avatar.jpg" width={200} flip="vertical" alt="Vertical Flip" />7. Pre-Defined System Presets
Use pre-configured presets for consistent design tokens across your app.
import { Image } from 'severmedia';
// Built-in presets: 'thumbnail', 'avatar', 'productCard', 'productPage', 'gallery', 'hero', 'logo', 'icon'
<Image src="users/john.jpg" preset="avatar" alt="Avatar preset" />
<Image src="store/jacket.jpg" preset="productCard" alt="Product Card preset" />
<Image src="banners/summer.jpg" preset="hero" alt="Hero Banner preset" />8. Fluid Responsive Images (srcSet)
Generates multi-resolution srcSet for retina and mobile display optimization.
import { Image } from 'severmedia';
<Image
src="demo/wallpaper.jpg"
responsive={true}
breakpoints={[320, 640, 768, 1024, 1440, 1920]}
sizes="(max-width: 768px) 100vw, 50vw"
alt="Fluid Responsive Image"
/>9. Programmatic Fluent image() Builder
Build signed CDN URLs programmatically for APIs, meta tags, or custom logic.
import { image } from 'severmedia';
// Fluent chaining
const avatarUrl = image('users/alex.jpg')
.width(200)
.height(200)
.fit('cover')
.quality(85)
.webp()
.url();
const heroBannerUrl = image('marketing/campaign.jpg')
.width(1440)
.height(500)
.crop('smart')
.quality(90)
.avif()
.url();10. File Uploading (upload() & useUpload())
Upload files to Sever Media storage buckets directly from your code or UI.
Direct Function Call:
import { upload } from 'severmedia';
const handleFileUpload = async (file: File) => {
const result = await upload(file, {
bucket: 'products',
folder: 'shoes',
filename: 'running-shoe.png',
});
if (result.success) {
console.log('Optimized WebP CDN URL:', result.transformedUrl);
console.log('Direct Storage URL:', result.directUrl);
}
};React Stateful Hook:
import { useUpload } from 'severmedia';
export function UploadWidget() {
const { uploadImage, uploading, result, error } = useUpload();
const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
const file = e.target.files?.[0];
if (file) {
await uploadImage(file, { folder: 'avatars' });
}
};
return (
<div className="space-y-4">
<input type="file" onChange={handleFileChange} disabled={uploading} />
{uploading && <p>Uploading to Sever Media...</p>}
{error && <p className="text-red-500">{error}</p>}
{result?.success && (
<img src={result.transformedUrl} alt="Uploaded preview" className="w-32 h-32 rounded-full" />
)}
</div>
);
}11. Image Updating & Replacement (useReplace())
Replace an existing image in MinIO with a new file while keeping the asset key intact.
import { useReplace } from 'severmedia';
export function UpdateAssetButton({ assetKey }: { assetKey: string }) {
const { replaceImage, replacing, error } = useReplace();
const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
const newFile = e.target.files?.[0];
if (newFile) {
const res = await replaceImage(assetKey, newFile);
if (res.success) {
alert('Image updated successfully!');
}
}
};
return (
<input type="file" onChange={handleFileChange} disabled={replacing} />
);
}12. Asset Deletion (useDelete())
Delete an asset from Sever Media storage.
import { useDelete } from 'severmedia';
export function DeleteAssetButton({ assetKey }: { assetKey: string }) {
const { deleteImage, deleting } = useDelete();
const handleDelete = async () => {
const success = await deleteImage(assetKey);
if (success) {
alert('Asset deleted from Sever Media');
}
};
return (
<button onClick={handleDelete} disabled={deleting}>
{deleting ? 'Deleting...' : 'Delete Asset'}
</button>
);
}13. Pre-Styled Dropzone UI (<ImageUploader />)
Include a ready-made drag & drop uploader in your app.
import { ImageUploader } from 'severmedia';
export function MediaUploadModal() {
return (
<ImageUploader
folder="user-uploads"
onSuccess={(res) => console.log('Upload complete:', res.transformedUrl)}
onError={(err) => console.error('Upload failed:', err)}
/>
);
}📄 License
MIT © Sever Media
