@betechspark/imageproxy-react

React 19 components and hooks for betechspark Image Proxy — plain <img> and next/image, with full transform support.

Built on @betechspark/imageproxy-client.

Install

# React / Vite / CRA
npm i @betechspark/imageproxy-react @betechspark/imageproxy-client

# Next.js (add next — usually already present)
npm i @betechspark/imageproxy-react @betechspark/imageproxy-client

Peers: react ^19, next >=14 (optional, only for @betechspark/imageproxy-react/next).

NEXT_PUBLIC_IMAGE_PROXY_URL=http://127.0.0.1:3001

Exports

| Import | Components / APIs | | ------ | ----------------- | | @betechspark/imageproxy-react | Image / ImageProxyImage, ImageProxyProvider, useImageProxySrc, createNextImageLoader | | @betechspark/imageproxy-react/next | Image / ImageProxyNextImage (wraps next/image) |

Setup (all apps)

import { ImageProxyProvider } from '@betechspark/imageproxy-react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ImageProxyProvider baseUrl={process.env.NEXT_PUBLIC_IMAGE_PROXY_URL!}>
      {children}
    </ImageProxyProvider>
  );
}

Plain React — <Image />

'use client';

import { Image, ImageProxyProvider } from '@betechspark/imageproxy-react';

export function ProductCard({ fileId }: { fileId: string }) {
  return (
    <Image
      route="uuid"
      id={fileId}
      alt="Product photo"
      transforms={{
        w: 600,
        h: 400,
        fit: 'cover',
        pos: 'entropy',
        f: 'webp',
        q: 85,
      }}
      style={{ maxWidth: '100%', height: 'auto' }}
    />
  );
}

Transform props (transforms)

All Image Proxy query parameters are supported, including aliases:

| Category | Fields | | -------- | ------ | | Size | w, h, width, height, fit, pos, position | | Format | f, format, q, quality, progressive | | Fast path | thumb, thumbnail | | Effects | blur, blur_type, pixelate, sharpen, sharp |

Extra string keys are forwarded (forward-compatible).

Examples — routes

Catalog UUID (GET /image/:id):

<Image route="uuid" id={fileId} alt="Hero" transforms={{ w: 1920, h: 1080, fit: 'cover', f: 'webp' }} />

File Server id (GET /asset/... + fileserver/<id>):

<Image
  route="fileserver"
  fileId={fileId}
  alt="Avatar"
  transforms={{ w: 128, h: 128, fit: 'cover', thumb: true, f: 'webp' }}
  auth={{ exp, sig }}
/>

Filesystem / S3 / remote URL (raw sourceKey):

<Image
  route="asset"
  sourceKey="fs/uploads/gallery/hero.png"
  alt="Gallery"
  transforms={{ w: 800, blur: 12, blur_type: 'gaussian', sharpen: 2 }}
/>

<Image
  route="asset"
  sourceKey={`url/${encodeURIComponent('https://cdn.example/photo.jpg')}`}
  alt="Remote"
  transforms={{ w: 640, fit: 'contain', f: 'jpeg', q: 90 }}
/>

Privacy / effects:

<Image route="uuid" id={fileId} alt="Blurred" transforms={{ blur: 50, blur_type: 'gaussian' }} />
<Image route="uuid" id={fileId} alt="Pixelated" transforms={{ pixelate: 16 }} />

Next.js — <Image /> from /next

'use client';

import { Image } from '@betechspark/imageproxy-react/next';

export function Hero({ fileId }: { fileId: string }) {
  return (
    <Image
      route="uuid"
      id={fileId}
      alt="Hero banner"
      width={1200}
      height={630}
      priority
      transforms={{
        w: 1200,
        h: 630,
        fit: 'cover',
        pos: 'center',
        f: 'webp',
        q: 82,
        progressive: true,
      }}
    />
  );
}

Fill layout:

<div style={{ position: 'relative', width: '100%', aspectRatio: '16/9' }}>
  <Image
    route="uuid"
    id={fileId}
    alt="Background"
    fill
    sizes="100vw"
    width={1920}
    height={1080}
    transforms={{ w: 1920, h: 1080, fit: 'cover', f: 'webp' }}
  />
</div>

The Next component builds the full Image Proxy URL (including effects) and uses unoptimized on next/image, because transforms live in the query string — not in the default loader’s width/quality only.

Alternative: next/image loader (simple transforms)

For apps that only need w / q / f via the loader:

// lib/imageproxy-loader.ts
import { createNextImageLoader } from '@betechspark/imageproxy-react';

export default createNextImageLoader({
  baseUrl: process.env.NEXT_PUBLIC_IMAGE_PROXY_URL!,
});

Use when src is a UUID or fs/ / s3/ key — see USAGE.md.

Private images

| Route | Mechanism | | ----- | --------- | | route="uuid" + private catalog | JWT Authorization header — fetch URL + token from your API; use <img> or pass token via custom fetch (not built into <Image> yet) | | route="fileserver" | auth={{ exp, sig }} on <Image /> — from @betechspark/imageproxy-server |

Low-level hook

import { useImageProxySrc } from '@betechspark/imageproxy-react';

const src = useImageProxySrc({
  route: 'uuid',
  id: fileId,
  transforms: { w: 400, f: 'webp' },
});

See USAGE.md and apps/example-next-image-proxy.