@pixelfiddler/next

Next.js image component for PixelFiddler image transformations. A drop-in wrapper around next/image with automatic optimization through PixelFiddler CDN.

Installation

npm install @pixelfiddler/next
# or
pnpm add @pixelfiddler/next
# or
yarn add @pixelfiddler/next

Note: This package requires next >= 13.0.0 and react >= 18.2.0 as peer dependencies.

Quick Start

import { PixelFiddlerImage } from '@pixelfiddler/next';

function App() {
  return (
    <PixelFiddlerImage
      src="https://example.com/photo.jpg"
      alt="A beautiful photo"
      width={800}
      height={600}
      transformations={{ format: 'WEBP', quality: 80 }}
    />
  );
}

Components

PixelFiddlerImage

A wrapper around Next.js Image component that uses PixelFiddler as the image loader for automatic optimization.

import { PixelFiddlerImage } from '@pixelfiddler/next';

// Basic usage with dimensions
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Profile photo"
  width={400}
  height={300}
/>

// Fill container
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Hero image"
  fill
  sizes="(max-width: 768px) 100vw, 50vw"
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | required | URL of the image (relative or absolute). Relative paths are attached to baseUrl | | baseUrl | string | - | Base URL endpoint from PixelFiddler Dashboard. Can be set via PixelFiddlerProvider | | sizes | string | - | Sizes attribute for responsive images (e.g., "(max-width: 768px) 100vw, 50vw") | | responsive | boolean | true | Enable automatic srcset generation via PixelFiddler loader | | transformations | TransformationOptions | - | Image transformation options |

All standard Next.js Image props (width, height, fill, quality, priority, placeholder, unoptimized, className, etc.) are also supported.

PixelFiddlerProvider

A context provider for sharing configuration across all PixelFiddlerImage components.

import { PixelFiddlerProvider, PixelFiddlerImage } from '@pixelfiddler/next';

function App() {
  return (
    <PixelFiddlerProvider config={{ baseUrl: 'https://cdn.example.com' }}>
      <PixelFiddlerImage src="/photos/hero.jpg" alt="Hero" fill sizes="100vw" />
      <PixelFiddlerImage src="/photos/thumb.jpg" alt="Thumbnail" width={200} height={200} />
    </PixelFiddlerProvider>
  );
}

Props

| Prop | Type | Description | |------|------|-------------| | config | PixelFiddlerConfig | Configuration object with baseUrl and optional maxDpr | | children | ReactNode | Child components |

Usage Examples

Basic Transformations

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Transformed image"
  width={800}
  height={600}
  transformations={{
    format: 'WEBP',
    quality: 85,
    blur: 10,
  }}
/>

Fill Container

Use fill prop for images that should fill their parent container:

<div style={{ position: 'relative', width: '100%', height: '400px' }}>
  <PixelFiddlerImage
    src="https://example.com/hero.jpg"
    alt="Hero banner"
    fill
    sizes="100vw"
    style={{ objectFit: 'cover' }}
    transformations={{ format: 'WEBP' }}
  />
</div>

Priority Loading

For above-the-fold images, use priority to preload:

<PixelFiddlerImage
  src="https://example.com/hero.jpg"
  alt="Hero image"
  width={1200}
  height={600}
  priority
  transformations={{ format: 'WEBP' }}
/>

Disable Responsive Behavior

When responsive is false, the image URL is built with exact transformations and no srcset is generated:

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Non-responsive"
  width={400}
  height={300}
  responsive={false}
  transformations={{ width: 400, height: 300, format: 'WEBP' }}
/>

Unoptimized Images

Skip the PixelFiddler loader entirely:

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Unoptimized"
  width={400}
  height={300}
  unoptimized
/>

With Quality Override

The quality prop is passed to transformations:

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="High quality"
  width={800}
  height={600}
  quality={95}
/>

Responsive Sizes

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Responsive image"
  fill
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
  transformations={{ format: 'WEBP' }}
/>

How It Works

The component uses a custom Next.js image loader that:

1. Receives width requests from Next.js's responsive image system
2. Builds PixelFiddler transformation URLs with the requested width
3. Applies any additional transformations you specify

This means Next.js handles the responsive srcset generation while PixelFiddler handles the actual image transformations and delivery.

TypeScript

Full TypeScript support with exported types:

import type {
  PixelFiddlerImageProps,
  PixelFiddlerContextValue,
  TransformationOptions,
  ResizeOptions,
  FormatOptions,
  EffectOptions,
  CropOptions,
  BorderOptions,
  TextOptions,
  WatermarkOptions,
  PixelFiddlerConfig,
} from '@pixelfiddler/next';

Related

• @pixelfiddler/core - Core utilities for building transformation URLs
• @pixelfiddler/react - React components for non-Next.js projects

License

MIT