vite-vanjs-svg

0.0.14 verified Mon Apr 27 auth: no javascript

A Vite plugin that transforms SVG files into VanJS components using DOMParser. Version 0.0.14 is the latest stable release with active development. It supports TypeScript, HMR, configurable include/exclude filters, and uses oxc/esbuild for transformation. Compared to alternatives, it is specifically designed for VanJS, providing fast transformation and type safety without runtime overhead.

Common errors

error Cannot find module 'vite-vanjs-svg' or its corresponding type declarations. ↓

cause Missing TypeScript type reference or package not installed as devDependency.

fix

Run npm install -D vite-vanjs-svg and add /// <reference types="vite-vanjs-svg" /> to your vite-env.d.ts.

error Uncaught (in promise) TypeError: van is not a function ↓

cause Attempting to use SVG component outside of VanJS context or missing VanJS import.

fix

Ensure vanjs-core or vanjs-ui is imported and van.tags is available.

error [plugin:vite-vanjs-svg] The 'style' attribute only supports string value. ↓

cause Passing an object (e.g., style={{ fill: 'red' }}) instead of a string.

fix

Change style to a string like 'fill: red'.

error Failed to load url ./icon.svg?van (doesn't exist) ↓

cause SVG file path is incorrect or missing the ?van query.

fix

Verify the SVG path and ensure the import ends with ?van.

Warnings

deprecated esbuildOptions is deprecated since version 0.0.14; use oxcOptions instead. ↓

fix Replace esbuildOptions with oxcOptions in plugin configuration.

breaking Components are now ES modules with sourcemaps; if you rely on UMD or CommonJS output, this may break imports. ↓

fix Ensure your project uses ESM-compatible bundler settings.

gotcha The style attribute only supports string values; object or array style values will not work. ↓

fix Pass style as a string (e.g., 'fill: red').

gotcha Include filter defaults to ['**/*.svg?van']; if you omit ?van query, SVGs won't be transformed. ↓

fix Append ?van to SVG import paths or customize include option.

Install

npm install vite-vanjs-svg

yarn add vite-vanjs-svg

pnpm add vite-vanjs-svg

Imports

vanSVG

wrong

const vanSVG = require('vite-vanjs-svg')

correct

import vanSVG from 'vite-vanjs-svg'

ESM only; also works with default import for Vite config.

VitePluginVanSvgOptions

wrong

import { VitePluginVanSvgOptions } from 'vite-vanjs-svg'

correct

import type { VitePluginVanSvgOptions } from 'vite-vanjs-svg'

Only exported as type; import with 'type' modifier to avoid runtime issues.

Icon default import
wrong
```
import { Icon } from './icon.svg?van'
```
correct
```
import Icon from './icon.svg?van'
```
SVG with query ?van is imported as default export; named import will fail.

Quickstart

Configure the Vite plugin, add TypeScript declarations, and use an imported SVG as a VanJS component.

// vite.config.ts
import { defineConfig } from 'vite';
import vanSVG from 'vite-vanjs-svg';

export default defineConfig({
  plugins: [
    vanSVG({
      // Optional: include: ['**/*.svg?van'],
      // exclude: undefined,
      // esbuildOptions: {},
      // oxcOptions: {},
    }),
  ],
});

// src/vite-env.d.ts
/// <reference types="vite/client" />
/// <reference types="vite-vanjs-svg" />

// App.tsx (example with VanJS)
import van from 'vanjs-core';
import Icon from './icon.svg?van';

const { div } = van.tags;

const App = () => {
  return div(
    Icon({
      width: 24,
      height: 24,
      class: 'my-icon',
      style: 'fill: currentColor'
    })
  );
};

document.body.appendChild(App());