npm package: @pixelfiddler/next
Description: Next.js image component and loader for PixelFiddler image transformation SDK
Author: PixelFiddler
Latest version: 1.0.5

# @pixelfiddler/next

Next.js image component for [PixelFiddler](https://pixel-fiddler.com) image transformations. A drop-in wrapper around `next/image` with automatic optimization through PixelFiddler CDN.

## Installation

```bash
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

```tsx
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.

```tsx
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.

```tsx
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

```tsx
<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:

```tsx
<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:

```tsx
<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:

```tsx
<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:

```tsx
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Unoptimized"
  width={400}
  height={300}
  unoptimized
/>
```

### With Quality Override

The `quality` prop is passed to transformations:

```tsx
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="High quality"
  width={800}
  height={600}
  quality={95}
/>
```

### Responsive Sizes

```tsx
<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:

```typescript
import type {
  PixelFiddlerImageProps,
  PixelFiddlerContextValue,
  TransformationOptions,
  ResizeOptions,
  FormatOptions,
  EffectOptions,
  CropOptions,
  BorderOptions,
  TextOptions,
  WatermarkOptions,
  PixelFiddlerConfig,
} from '@pixelfiddler/next';
```

## Related

- [@pixelfiddler/core](https://www.npmjs.com/package/@pixelfiddler/core) - Core utilities for building transformation URLs
- [@pixelfiddler/react](https://www.npmjs.com/package/@pixelfiddler/react) - React components for non-Next.js projects

## License

MIT