next-image-cache-placeholder

A high-performance, cache-backed image placeholder generator and responsive React component wrapper for Next.js.

Features

• ⚡️ Zero-Fetch CDNs: Automatically detects and rewrites image URLs from popular CDNs (Unsplash, Cloudinary, Imgix, Shopify) to fetch tiny, highly-optimized images directly.
• 🎨 Deterministic Abstract Gradients: Instant, zero-network, responsive HSL gradient placeholder generation for non-CDN images based on their URL string.
• 💾 Plug-and-Play Caching: Built-in in-memory and disk-caching (.next/cache) to prevent redundant generation. Easily hook up custom stores (e.g. Redis, Upstash, Vercel KV).
• 📱 Fully Responsive component: Comes with <CachedImage>, a wrapper around next/image that supports fill, responsive aspect ratios, and smooth CSS fade-in transitions.
• 📦 Zero Runtime Dependencies: Extremely lightweight and optimized for both Node.js and Edge runtimes.

Installation

npm install next-image-cache-placeholder

Basic Usage

1. App Router (React Server Component)

Generate the placeholder on the server and pass it to the responsive <CachedImage> component.

// app/page.tsx
import { getPlaceholder, CachedImage } from 'next-image-cache-placeholder';

export default async function Page() {
  const imageUrl = 'https://images.unsplash.com/photo-1579783902614-a3fb3927b6a5';
  
  // Generates and caches the blur placeholder base64 URL
  const placeholder = await getPlaceholder(imageUrl, {
    strategy: 'blur', // 'blur' | 'pixelate' | 'color'
  });

  return (
    <main style={{ padding: '2rem', maxWidth: '800px', margin: '0 auto' }}>
      <h1>Aesthetic Gallery</h1>
      
      {/* Responsive Aspect Ratio Image */}
      <div style={{ width: '100%', aspectRatio: '16/9', position: 'relative' }}>
        <CachedImage
          src={imageUrl}
          alt="Abstract artwork"
          placeholderDataURL={placeholder}
          fill
          sizes="(max-width: 768px) 100vw, 800px"
          priority
        />
      </div>
    </main>
  );
}

2. Pages Router (getStaticProps or getServerSideProps)

// pages/index.tsx
import { GetStaticProps } from 'next';
import { getPlaceholder, CachedImage } from 'next-image-cache-placeholder';

interface HomeProps {
  imageUrl: string;
  placeholder: string;
}

export default function Home({ imageUrl, placeholder }: HomeProps) {
  return (
    <div style={{ maxWidth: '600px', margin: '2rem auto' }}>
      <CachedImage
        src={imageUrl}
        alt="Aesthetic placeholder example"
        placeholderDataURL={placeholder}
        width={600}
        height={400}
        animationDuration={500} // Custom fade-in speed (ms)
      />
    </div>
  );
}

export const getStaticProps: GetStaticProps = async () => {
  const imageUrl = 'https://images.unsplash.com/photo-1493612276216-ee3925520721';
  const placeholder = await getPlaceholder(imageUrl);

  return {
    props: {
      imageUrl,
      placeholder,
    },
  };
};

Advanced Configurations

Custom Caching Store (Redis / Upstash / Vercel KV)

You can pass a custom cache store that implements the CacheStore interface.

import { getPlaceholder, CacheStore } from 'next-image-cache-placeholder';
import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: 'UPSTASH_REDIS_REST_URL',
  token: 'UPSTASH_REDIS_REST_TOKEN',
});

// Implement the CacheStore interface
const redisStore: CacheStore = {
  get: async (key) => await redis.get(key),
  set: async (key, value) => {
    await redis.set(key, value, { ex: 86400 * 7 }); // Expiry 7 days
  },
};

// Use the custom store
const placeholder = await getPlaceholder(src, {
  cacheStore: redisStore,
});

Options API (getPlaceholder)

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | strategy | 'blur' \| 'pixelate' \| 'color' | 'blur' | Placeholder style strategy. | | cache | boolean | true | Enable or disable reading/writing cache. | | cacheStore | CacheStore | globalFileCache | Custom CacheStore engine. Falls back to in-memory on Edge runtimes. | | width | number | 10 | Resizing width (pixels) requested from the CDNs. | | height | number | 10 | Resizing height (pixels). | | quality | number | 20 | Fetching quality (1-100) requested from the CDNs. | | fallbackColor | string | '#e5e7eb' | Solid fallback color hex/hsl. |

License

MIT © 2026.