Frontend Usage Guide

The staticdelivr npm package provides a React component for automatic image optimization through our CDN. Perfect for React, Next.js, and other modern JavaScript frameworks.

Features

Automatic CDN URLs: Generate optimized CDN URLs for your images
Format Conversion: Automatically convert to WebP/AVIF for modern browsers
Responsive Images: Easy width and height configuration
Quality Control: Fine-tune compression for the perfect balance
Drop-in Replacement: Replace <img> tags seamlessly

Installation

Install the package via npm or yarn:

npm install staticdelivr

Or with yarn:

yarn add staticdelivr

Quick Start

Basic Usage

import React from 'react';
import { StaticDelivrImage } from 'staticdelivr';

function App() {
  return (
    <StaticDelivrImage
      src="https://example.com/images/hero.jpg"
      width={800}
      height={600}
      quality={80}
      format="webp"
      alt="Hero image"
    />
  );
}

export default App;

The component automatically generates an optimized CDN URL:

https://cdn.staticdelivr.com/img/images?url=https://example.com/images/hero.jpg&w=800&h=600&q=80&format=webp

Configuration

Global Base URL

For relative image paths, configure a global base URL. This is useful when all your images are hosted on the same domain.

// In your app entry point (e.g., _app.tsx, index.tsx)
import { StaticDelivr } from 'staticdelivr';

// Set the base URL once
StaticDelivr.set({ baseURL: 'https://example.com' });

Now you can use relative paths:

// This will resolve to https://example.com/images/photo.jpg
<StaticDelivrImage
  src="/images/photo.jpg"
  width={400}
/>

Next.js Configuration

In a Next.js app, configure the base URL in _app.tsx or _app.js:

// pages/_app.tsx
import { StaticDelivr } from 'staticdelivr';

// Configure base URL for your domain
StaticDelivr.set({ baseURL: 'https://your-domain.com' });

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

Component Props

The StaticDelivrImage component accepts the following props:

Prop	Type	Required	Default	Description
`src`	string	Yes	-	Image source URL (absolute or relative)
`width`	number	No	-	Desired width in pixels
`height`	number	No	-	Desired height in pixels
`quality`	number	No	100	Compression quality (1-100)
`format`	string	No	-	Output format: `webp`, `avif`, `jpeg`, `png`
`alt`	string	No	`''`	Alt text for accessibility
`className`	string	No	-	CSS class names

Examples

Responsive Product Images

import { StaticDelivrImage } from 'staticdelivr';

function ProductCard({ product }) {
  return (
    <div className="product-card">
      <StaticDelivrImage
        src={product.imageUrl}
        width={400}
        height={400}
        quality={85}
        format="webp"
        alt={product.name}
        className="product-image"
      />
      <h3>{product.name}</h3>
      <p>${product.price}</p>
    </div>
  );
}

Hero Section with Large Image

import { StaticDelivrImage } from 'staticdelivr';

function HeroSection() {
  return (
    <section className="hero">
      <StaticDelivrImage
        src="https://example.com/hero-background.jpg"
        width={1920}
        height={1080}
        quality={80}
        format="webp"
        alt="Hero background"
        className="hero-bg"
      />
      <div className="hero-content">
        <h1>Welcome</h1>
      </div>
    </section>
  );
}

Thumbnail Gallery

import { StaticDelivrImage } from 'staticdelivr';

function Gallery({ images }) {
  return (
    <div className="gallery">
      {images.map((image, index) => (
        <StaticDelivrImage
          key={index}
          src={image.url}
          width={150}
          height={150}
          quality={70}
          format="webp"
          alt={image.caption}
          className="thumbnail"
        />
      ))}
    </div>
  );
}

Avatar Component

import { StaticDelivrImage } from 'staticdelivr';

function Avatar({ user, size = 'medium' }) {
  const sizes = {
    small: 32,
    medium: 48,
    large: 96
  };

  const dimension = sizes[size];

  return (
    <StaticDelivrImage
      src={user.avatarUrl}
      width={dimension}
      height={dimension}
      quality={90}
      format="webp"
      alt={`${user.name}'s avatar`}
      className={`avatar avatar-${size}`}
    />
  );
}

Format Selection Guide

Choose the right format for your use case:

Format	Best For	Browser Support
`webp`	General use, photos, graphics	97%+ browsers
`avif`	Best compression, modern apps	85%+ browsers
`jpeg`	Legacy support, photos	100% browsers
`png`	Transparency, graphics	100% browsers

Recommendation: Use webp for the best balance of compression and compatibility.

Quality Guidelines

Quality	File Size	Visual Quality	Use Case
90-100	Large	Excellent	Hero images, product photos
75-89	Medium	Very Good	General content images
50-74	Small	Good	Thumbnails, backgrounds
Below 50	Tiny	Acceptable	Low-priority images

Recommendation: Start with quality 80 and adjust based on your needs.

Advanced Usage

Direct URL Generation

If you need to generate CDN URLs without the component:

import { StaticDelivr } from 'staticdelivr';

// Get the configured base URL
const { baseURL } = StaticDelivr.get();

// Build your own URL
function buildCdnUrl(imagePath, options = {}) {
  const { width, height, quality = 80, format = 'webp' } = options;
  
  const fullUrl = imagePath.startsWith('http') 
    ? imagePath 
    : `${baseURL}${imagePath}`;
  
  let cdnUrl = `https://cdn.staticdelivr.com/img/images?url=${encodeURIComponent(fullUrl)}`;
  
  if (width) cdnUrl += `&w=${width}`;
  if (height) cdnUrl += `&h=${height}`;
  if (quality) cdnUrl += `&q=${quality}`;
  if (format) cdnUrl += `&format=${format}`;
  
  return cdnUrl;
}

// Usage
const optimizedUrl = buildCdnUrl('/photos/hero.jpg', {
  width: 1200,
  quality: 85,
  format: 'webp'
});

Using with CSS Background Images

import { StaticDelivr } from 'staticdelivr';

function HeroWithBackground() {
  const { baseURL } = StaticDelivr.get();
  const imageUrl = `${baseURL}/images/hero-bg.jpg`;
  const cdnUrl = `https://cdn.staticdelivr.com/img/images?url=${encodeURIComponent(imageUrl)}&w=1920&q=75&format=webp`;

  return (
    <div 
      className="hero"
      style={{ backgroundImage: `url(${cdnUrl})` }}
    >
      <h1>Welcome</h1>
    </div>
  );
}

Lazy Loading Integration

import { StaticDelivrImage } from 'staticdelivr';

function LazyImage({ src, ...props }) {
  return (
    <StaticDelivrImage
      src={src}
      loading="lazy" // Native lazy loading
      {...props}
    />
  );
}

Image Optimization Limits

Our image optimization service has the following limits:

Limit	Value
Maximum width	4000px
Maximum height	4000px
Maximum file size	10MB
Supported formats	JPG, JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF

Images exceeding these limits will return an error.

Migrating from Next/Image

If you're migrating from Next.js's built-in Image component:

Before (Next/Image):

import Image from 'next/image';

<Image
  src="/photos/hero.jpg"
  width={800}
  height={600}
  quality={80}
  alt="Hero"
/>

After (StaticDelivrImage):

import { StaticDelivrImage, StaticDelivr } from 'staticdelivr';

// In _app.tsx
StaticDelivr.set({ baseURL: 'https://your-domain.com' });

// In component
<StaticDelivrImage
  src="/photos/hero.jpg"
  width={800}
  height={600}
  quality={80}
  format="webp"
  alt="Hero"
/>

Troubleshooting

Images Not Loading

Check the source URL: Ensure the image URL is accessible publicly
Verify base URL: Make sure StaticDelivr.set() is called before components render
Check for CORS issues: The origin server must allow our CDN to fetch images

Poor Image Quality

Increase quality setting: Try quality 85-95 for important images
Use appropriate format: PNG for graphics with text, WebP/AVIF for photos
Check source image: Low-quality source images can't be improved

Images Too Large

Add width/height props: Always specify dimensions to avoid serving full-size images
Reduce quality: Try quality 70-80 for most use cases
Use WebP/AVIF: These formats provide better compression

Support

npm Package: npmjs.com/package/staticdelivr
GitHub: StaticDelivr/StaticDelivr-CDN-NPM-Package
Documentation: staticdelivr.com/docs
Email: contact@staticdelivr.com