vite-plugin-image-srcset

Simple Vite plugin to generate srcset attributes for responsive images.

Import a single image and get src + srcSet for 1x/2x/3x pixel densities.

Installation

pnpm

pnpm add -D vite-plugin-image-srcset

npm

npm install -D vite-plugin-image-srcset

yarn

yarn add -D vite-plugin-image-srcset

Setup

1. Add plugin to Vite config

// vite.config.ts
import { defineConfig } from 'vite';
import { srcSetPlugin } from 'vite-plugin-image-srcset';

export default defineConfig({
  plugins: [srcSetPlugin()],
});

2. Add types (TypeScript)

Add to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["vite-plugin-image-srcset/client"]
  }
}

Or add a reference in your vite-env.d.ts:

  /// <reference types="vite/client" />
+ /// <reference types="vite-plugin-image-srcset/client" />

Usage

File structure

The plugin expects images with @2x and @3x suffixes:

assets/
  icon.png      # 1x (base)
  icon@2x.png   # 2x
  icon@3x.png   # 3x

Missing densities are skipped rather than failing the build — if only icon.png and icon@2x.png exist, the generated srcSet contains just those two candidates.

Import with ?srcset query

import icon from './assets/icon.png?srcset';

// icon = { src: '/assets/icon.png', srcSet: '/assets/icon.png 1x, /assets/icon@2x.png 2x, /assets/icon@3x.png 3x' }

React example

import icon from './assets/icon.png?srcset';

function App() {
  return <img {...icon} alt="Icon" />;
}

HTML example

import icon from './assets/icon.png?srcset';

document.body.innerHTML = `<img src="${icon.src}" srcset="${icon.srcSet}" alt="Icon" />`;

API

The plugin transforms imports with ?srcset query into an object:

interface ImageSrcSet {
  src: string; // URL of the lowest available density
  srcSet: string; // srcset string: "url1 1x, url2 2x, url3 3x"
}

Options

srcSetPlugin({
  densities: [1, 2, 3], // Pixel densities to generate.
  suffix: (baseName, density) => `${baseName}@${density}x`, // Builds the file name for densities > 1.
  extensions: ['.png', '.jpg', '.jpeg', '.webp', '.avif'], // Extensions handled by the plugin.
});

Supported formats

• .png
• .jpg / .jpeg
• .webp
• .avif

Other extensions are left untouched. The list is configurable via the extensions option, but the bundled type declarations only cover the formats above — for anything else, declare the module yourself:

declare module '*.gif?srcset' {
  const srcset: import('vite-plugin-image-srcset').ImageSrcSet;
  export default srcset;
}

License

MIT