npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@desource/image-react

v0.6.0

Published

High-quality image optimization for React and Next.js with responsive output, deployment-aware provider selection, dozens of built-in provider modules, and IPX.

Readme

AI-assisted development moves ideas into working products quickly. DeSource Image keeps image preparation inside that development loop. Add one suitable local or remote source, then control its output with component props.

Keep /img/hero.jpg instead of exporting hero-480.webp, hero-960.webp, and hero-1600.webp. DeSource Image turns one image input into provider URLs, responsive srcset, <picture> sources, placeholders, preload metadata, presets, aliases, source validation, and local IPX routes.

For MVPs and everyday product development, image quality becomes a code edit. Change quality={80} to quality={65} and keep the same source file, component, and URL.

@desource/image-react provides components for common cases, hooks for application-owned markup, a loader for next/image, and server helpers for Vite and the Next.js App Router. Every API renders or supplies native <img> and <picture> markup.

Provider configuration is optional. On Vercel, Netlify, or AWS Amplify, DeSource Image selects the platform image service from the deployment environment. Everywhere else, it falls back to the built-in IPX path. An explicit provider always wins.

Why DeSource Image for React?

React has no built-in image optimization layer. Next.js has a strong image pipeline for Next-only applications. DeSource Image adds deployment-aware provider selection, built-in provider modules, local IPX, and image rules that can also work outside Next.js.

  • Built for fast product iterations. Change image quality, format, crop, or responsive sizes in JSX. Source files and filenames stay unchanged.
  • One source instead of exported variants. Start with one suitable image and generate the widths and formats each screen needs.
  • Deployment-aware provider selection. Leave provider on auto. DeSource Image detects Vercel, Netlify, or AWS Amplify and uses IPX for local or other environments.
  • Vite and Next.js use the same image model. Keep the same inputs, presets, aliases, and providers across applications.
  • Native framework APIs. Use DsImage and DsPicture, or spread hook results onto elements owned by a design system. Output remains native <img> and <picture> markup.
  • Dozens of built-in provider modules. Import one provider subpath, use the complete registry, or register a typed custom provider.
  • Built-in local optimizer. Vite middleware and a Next.js App Router route handler serve IPX transformations without a separate image service.
  • next/image remains available. createNextImageLoader() lets Next own rendering while DeSource Image owns provider URLs.

How it compares

| Option | Best fit | How optimization is selected | Choose DeSource Image when | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | React <img> | Native browser images when the application owns its markup and URLs | No optimizer is selected. The browser requests src unchanged; deploying to Vercel, Netlify, or Amplify does not rewrite it. | You want to control responsive sizes, format, and quality in component code instead of exporting variants or maintaining srcset and <picture> markup. You also want placeholders, preloads, and an optimizer that follows the deployment. | | next/image | Next-only applications using the Next.js image pipeline | Next.js optimizer by default. Vercel, Netlify, and AWS Amplify integrate next/image with their hosting pipelines. For other image services, Next.js provides a custom-loader API rather than a provider catalog. | You want broader built-in provider support without replacing the component, or provider policy, presets, aliases, and source rules must remain stable across frameworks, hosts, and image services. | | Unpic React | Cross-framework responsive images already hosted on recognizable CDN or CMS URLs | Detects the provider from each src URL. Local or unknown sources need a fallback or explicit provider; the deployment itself is not the selection signal. | Vercel, Netlify, or AWS Amplify should choose the optimizer for every source, including relative paths, and you also need presets, aliases, source rules, <picture>, or server adapters. |

For a Next-only application, next/image remains the good candidate. DeSource Image is the stronger choice when that hosting-native workflow must extend beyond Next.js, or when provider policy, presets, aliases, and source rules must remain stable across frameworks, hosts, and image services.

Install

npm install @desource/image-react

Install ipx only when the app serves local /_ipx transformations itself:

npm install ipx

ipx, vite, and next are optional peers. Hosted providers such as Vercel, Netlify, Cloudinary, Imgix, Sanity, or ImageKit do not need the local optimizer.

Quick start

import { DsImage, DsPicture } from '@desource/image-react';

export function Gallery() {
  return (
    <>
      <DsImage
        src="/img/hero.jpg"
        alt="Mountain lake at sunrise"
        width={1600}
        height={1000}
        sizes="100vw md:760px"
        format="webp"
        quality={76}
        placeholder
        preload={{ fetchPriority: 'high' }}
        className="hero"
      />

      <DsPicture
        src="/img/card.jpg"
        alt="Cabin under the stars"
        width={960}
        height={640}
        formats={['avif', 'webp']}
        fallbackFormat="jpg"
        imgAttrs={{ className: 'card-image' }}
      />
    </>
  );
}

Both components render native elements. DsImage forwards refs to the <img>; DsPicture forwards refs to the <picture>.

Configure once

import { DsImageProvider } from '@desource/image-react';
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

export function App() {
  return (
    <DsImageProvider
      config={{
        provider: 'cloudinary',
        quality: 80,
        screens: { sm: 640, md: 768, lg: 1024 },
        domains: ['images.example.com'],
        providers: {
          cloudinary: cloudinaryProvider({ cloudName: 'demo' })
        },
        presets: {
          avatar: { width: 96, height: 96, fit: 'cover', format: 'webp' }
        }
      }}
    >
      <Gallery />
    </DsImageProvider>
  );
}

Configuration is optional. With no explicit provider, the shared runtime detects Vercel, Netlify, or AWS Amplify from the build environment and falls back to IPX.

DsImage component

import { DsImage } from '@desource/image-react';

export function Hero() {
  return (
    <DsImage
      src="/img/hero.jpg"
      alt="Aurora above a mountain lake"
      width={1600}
      height={900}
      sizes="100vw md:50vw lg:800px"
      format="webp"
      quality={82}
      placeholder
      preload={{ fetchPriority: 'high' }}
      className="hero"
      onLoad={() => console.log('loaded')}
    />
  );
}

alt is required. React-native props such as className, style, crossOrigin, fetchPriority, referrerPolicy, onLoad, and onError are supported. Lowercase fetchpriority and crossorigin aliases are also accepted when sharing options across frameworks.

DsPicture component

import { DsPicture } from '@desource/image-react';

export function ResponsiveHero() {
  return (
    <DsPicture
      src="/img/hero.jpg"
      alt="Responsive mountain landscape"
      width={1600}
      height={900}
      sizes="100vw md:50vw lg:800px"
      formats={['avif', 'webp']}
      fallbackFormat="jpg"
      className="hero-frame"
      imgAttrs={{ className: 'hero' }}
    />
  );
}

The component renders a native <picture> with ordered <source> elements and a fallback <img>. Comma-separated format="avif,webp", array format, and the legacyFormat alias are supported.

Hooks for native markup

Use hooks when a design-system component or application template must own the final DOM:

import { useDsImageProps, useDsPictureProps } from '@desource/image-react';

function NativeImage() {
  const img = useDsImageProps({
    src: '/img/card.jpg',
    alt: 'A coastal village',
    width: 720,
    height: 480,
    placeholder: true,
    className: 'card-image'
  });

  return <img {...img} />;
}

function NativePicture() {
  const picture = useDsPictureProps({
    src: '/img/card.jpg',
    alt: 'A coastal village at sunset',
    width: 720,
    height: 480,
    formats: ['avif', 'webp'],
    fallbackFormat: 'jpg',
    imgAttrs: { className: 'card-image' }
  });

  return (
    <picture {...picture.pictureProps}>
      {picture.sources.map((source) => (
        <source key={`${source.type}:${source.srcSet}`} {...source} />
      ))}
      <img {...picture.imgProps} />
    </picture>
  );
}

The hooks handle placeholder preload/decode state, load/error forwarding, and head preload links with reference counting.

Custom render

Use custom when generated image props should be rendered inside custom markup:

import { DsImage } from '@desource/image-react';

export function Figure() {
  return (
    <DsImage src="/img/hero.jpg" alt="Mountain lake" width={1200} placeholder custom>
      {({ imgProps, src, isLoaded }) => (
        <figure data-src={src} data-loaded={isLoaded}>
          <img {...imgProps} />
          <figcaption>Mountain lake</figcaption>
        </figure>
      )}
    </DsImage>
  );
}

Callable helper

import { useDsImage } from '@desource/image-react';

function Avatar({ src }: { src: string }) {
  const image = useDsImage();
  return <img src={image(src, { width: 96, height: 96, fit: 'cover' })} alt="" />;
}

The callable helper exposes getImage, getSizes, getMeta, getAttrs, getPicture, getPreloadLink, and configured preset shortcuts.

Next.js

Use DeSource Image components directly

The main package entry is a client entry because placeholders and head preloads use browser lifecycle APIs.

'use client';

import { DsImage } from '@desource/image-react';

export function ProductImage() {
  return <DsImage src="/products/chair.jpg" alt="Oak chair" width={1200} height={900} format="webp" />;
}

For hosted providers, configure the provider as usual. For local IPX URLs, add an App Router route handler.

Use DeSource Image with next/image

// ds-loader.ts
import { createNextImageLoader } from '@desource/image-react/next';

export const dsLoader = createNextImageLoader({
  provider: 'vercel'
});
import NextImage from 'next/image';
import { dsLoader } from './ds-loader';

export function Hero() {
  return <NextImage loader={dsLoader} src="/img/hero.jpg" alt="Hero" width={1200} height={800} />;
}

This lets next/image keep its rendering behavior while DeSource Image owns the provider URL rules.

App Router IPX route

// app/_ipx/[...path]/route.ts
import { createNextImageRouteHandler } from '@desource/image-react/next';

export const GET = createNextImageRouteHandler({
  dirs: ['public'],
  domains: ['images.example.com'],
  maxAge: 60 * 60 * 24 * 30
});

Remote optimization is denied by default. Add trusted domains, or set allowAllDomains: true only for an intentionally public optimizer.

Vite development optimizer

// vite.config.ts
import { dsImage } from '@desource/image-react/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [dsImage({ dirs: ['public'] })]
});

The plugin serves /_ipx during Vite development and preview. It also bakes a deterministic provider into client and SSR bundles so hydration uses the same provider.

Providers and presets

Register built-in or custom providers from the core package:

import { DsImageProvider } from '@desource/image-react';
import { imagekitProvider } from '@desource/image/providers/imagekit';

export function App() {
  return (
    <DsImageProvider
      config={{
        provider: 'imagekit',
        providers: {
          imagekit: imagekitProvider({ baseURL: 'https://ik.imagekit.io/demo' })
        },
        presets: {
          card: { width: 960, height: 640, sizes: '100vw md:480px', format: 'webp' }
        }
      }}
    >
      <DsImage preset="card" src="/products/chair.jpg" alt="Oak chair" />
    </DsImageProvider>
  );
}

Provider modules and custom-provider utilities are documented in @desource/image.

Links

License

MIT © 2026 DeSource Labs