esbuild-vanilla-image-loader

0.1.3 verified Fri May 01 auth: no javascript

esbuild-vanilla-image-loader is a plugin (v0.1.3) for esbuild that enables importing image files (PNG, JPG, GIF, etc.) within vanilla-extract .css.ts files when using vanilla-extract's Vite plugin. It bridges a gap where vanilla-extract's esbuild-based build cannot handle image imports, allowing background-image URLs or data URIs in CSS. It is stable but young, with no breaking changes yet. Unlike general asset modules, this specifically targets the vanilla-extract/esbuild integration, offering a filter option and dataUrl mode. Released under MIT.

Common errors

error Error: [esbuild] Cannot import file extension '.png' ↓

cause esbuild does not support importing images natively; the plugin is missing or misconfigured.

fix

Add import { ImageLoader } from 'esbuild-vanilla-image-loader' and include it in vanillaExtractPlugin's esbuildOptions.plugins.

error Cannot find module 'esbuild-vanilla-image-loader' or its corresponding type declarations. ↓

cause The package is not installed or TypeScript cannot resolve the types (no types field).

fix

Run pnpm add esbuild-vanilla-image-loader -D and ensure tsconfig includes node_modules types.

Warnings

gotcha This plugin only works when vanilla-extract uses esbuild (default with Vite plugin). If you use esbuildOptions incorrectly, the plugin won't apply. ↓

fix Ensure you pass esbuildOptions.plugins inside vanillaExtractPlugin(), not in the main Vite esbuild config.

gotcha Image imports in .css.ts files are resolved relative to the file, not the project root. This mirrors normal Vite behavior. ↓

fix Use relative paths from the .css.ts file to your image assets.

Install

npm install esbuild-vanilla-image-loader

yarn add esbuild-vanilla-image-loader

pnpm add esbuild-vanilla-image-loader

Imports

ImageLoader

wrong

import ImageLoader from 'esbuild-vanilla-image-loader'

correct

import { ImageLoader } from 'esbuild-vanilla-image-loader'

This package exports the plugin factory as a named export, not a default export.

Quickstart

Configures esbuild-vanilla-image-loader in a vanilla-extract Vite project, and imports an image in a .css.ts file.

// Install: pnpm add esbuild-vanilla-image-loader -D
// vite.config.ts
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
import { ImageLoader } from 'esbuild-vanilla-image-loader';

export default defineConfig({
  plugins: [
    vanillaExtractPlugin({
      esbuildOptions: {
        plugins: [ImageLoader()],
      },
    }),
  ],
});

// src/styles/App.css.ts
import { style } from '@vanilla-extract/css';
import Pic from './pic.png';

export const root = style({
  backgroundImage: `url(${Pic})`,
  height: 200,
  width: 200,
});