Next.js SDK

The Next.js PixelFiddler SDK provides a drop-in replacement for Next.js’s Image component with built-in PixelFiddler transformations and optimizations.

The SDK is lightweight with full TypeScript support. You can view the source code on GitHub.

Installation and Setup

Install the Next.js SDK via npm, pnpm, or yarn:

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

The SDK works with both the App Router and Pages Router in Next.js 13+.

This SDK exports the PixelFiddlerImage component which wraps Next.js’s Image component, automatically handling URL generation and transformations while preserving all Next.js image optimization features.

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

export default function Page() {
  return (
    <PixelFiddlerImage
      src="https://media.pixelfiddler.com/photos/hero.jpg"
      alt="Hero image"
      width={1200}
      height={600}
      transformations={{ format: 'WEBP', quality: 85 }}
    />
  );
}

You can wrap PixelFiddlerImage components inside the PixelFiddlerProvider to set a default baseUrl. This allows you to avoid repeating the base URL in every component, making your code cleaner and more maintainable.

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

export default function Page() {
  return (
    <PixelFiddlerProvider config={{ baseUrl: 'https://media.pixelfiddler.com' }}>
      <PixelFiddlerImage
        src="/photos/hero.jpg"
        alt="Hero image"
        width={1200}
        height={600}
      />
    </PixelFiddlerProvider>
  );
}

Exported Components

PixelFiddlerImage – A wrapper around Next.js Image component with automatic PixelFiddler transformations.
PixelFiddlerProvider – A context provider that shares configuration (like baseUrl) across all nested components.

Type Definitions

The SDK provides TypeScript definitions for all components, ensuring type safety and autocompletion in your IDE. Exported types include PixelFiddlerImageProps, PixelFiddlerContextValue, TransformationOptions, and all types from @pixelfiddler/core.

PixelFiddlerImage Component

The PixelFiddlerImage component is a wrapper around Next.js’s Image component. It allows you to use PixelFiddler’s URL generation and transformations while keeping all the benefits of Next.js image optimization.

It supports all Next.js Image props and additionally accepts the following PixelFiddler-specific props:

Parameter	Description
src (Required)	A relative or absolute path to the image. If a relative path is provided, it is appended to the `baseUrl`. If an absolute path is provided, it is used as-is. Example: `/photos/hero.jpg` or `https://example.com/image.jpg`
baseUrl	The base URL endpoint from your PixelFiddler Dashboard. To avoid passing this prop in every component, wrap your components in a `PixelFiddlerProvider`. Example: `https://media.pixelfiddler.com`
width	The width of the image in pixels. Required unless using `fill`.
height	The height of the image in pixels. Required unless using `fill`.
sizes	The sizes attribute for responsive images. Recommended when using `fill` or responsive layouts. Example: `sizes="(max-width: 768px) 100vw, 50vw"`
transformations	An object containing transformation options. See Transformations API for all available options.
responsive	A boolean that determines if responsive srcset generation is enabled. Defaults to `true`. Set to `false` to disable automatic srcset.

Basic Usage

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

export default function ProductCard() {
  return (
    <PixelFiddlerImage
      src="https://media.pixelfiddler.com/products/item.jpg"
      alt="Product image"
      width={400}
      height={300}
      transformations={{ format: 'WEBP', quality: 85 }}
    />
  );
}

Responsive Images

The component automatically generates responsive srcsets. Use the sizes prop to help the browser choose the right image size:

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

export default function ResponsiveImage() {
  return (
    <PixelFiddlerImage
      src="https://media.pixelfiddler.com/photos/hero.jpg"
      alt="Responsive hero"
      fill
      sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 800px"
      transformations={{ format: 'WEBP' }}
    />
  );
}

Disabling Responsive Images

If you want to disable automatic srcset generation, set responsive to false:

<PixelFiddlerImage
  src="https://media.pixelfiddler.com/photos/thumbnail.jpg"
  alt="Thumbnail"
  width={200}
  height={200}
  responsive={false}
  transformations={{ format: 'WEBP' }}
/>

Applying Transformations

You can apply various transformations to your images using the transformations prop. For a complete list of available options, see the Transformations API.

<PixelFiddlerImage
  src="/photos/product.jpg"
  alt="Product image"
  width={600}
  height={400}
  transformations={{
    format: 'WEBP',
    quality: 85,
    blur: 10,
  }}
/>

Using the Provider

The PixelFiddlerProvider component lets you configure default settings for all nested PixelFiddlerImage components. This is particularly useful in your root layout.

App Router Setup

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <PixelFiddlerProvider
          config={{
            baseUrl: process.env.NEXT_PUBLIC_PIXELFIDDLER_URL,
            maxDpr: 2
          }}
        >
          {children}
        </PixelFiddlerProvider>
      </body>
    </html>
  );
}

Pages Router Setup

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

export default function App({ Component, pageProps }) {
  return (
    <PixelFiddlerProvider
      config={{
        baseUrl: process.env.NEXT_PUBLIC_PIXELFIDDLER_URL,
        maxDpr: 2
      }}
    >
      <Component {...pageProps} />
    </PixelFiddlerProvider>
  );
}

Then use images anywhere without specifying baseUrl:

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

export default function ProductGrid({ products }) {
  return (
    <div className="grid grid-cols-4 gap-4">
      {products.map((product) => (
        <PixelFiddlerImage
          key={product.id}
          src={product.image}
          alt={product.name}
          width={300}
          height={300}
          transformations={{ format: 'WEBP', quality: 80 }}
        />
      ))}
    </div>
  );
}

Parameter	Description
config.baseUrl	Default base URL for all nested `PixelFiddlerImage` components.
config.maxDpr	Maximum device pixel ratio for srcset generation. Defaults to `2`.

TypeScript Support

The SDK provides full TypeScript support with exported types:

import type {
  PixelFiddlerImageProps,
  PixelFiddlerContextValue,
  TransformationOptions,
  PixelFiddlerConfig,
} from '@pixelfiddler/next';

For all transformation types, see the Transformations API.