npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

severmedia

v1.0.4

Published

Cloudinary alternative SDK for Sever Media image optimization, transformation, and storage.

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_key

Or 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