Vite SVG Loader

Common errors

• Cannot find module './my-icon.svg' or its corresponding type declarations.

  cause The TypeScript compiler does not recognize `.svg` files as modules that can be imported, usually due to a missing type declaration for `vite-svg-loader`.
  fix Add `/// <reference types="vite-svg-loader" />` to your `vite-env.d.ts` file.

• Error: [vite] The plugin 'vite-svg-loader' was not found. Have you installed it?

  cause The plugin is not installed or not correctly added to the `plugins` array in `vite.config.js/ts`.
  fix Run `npm install --save-dev vite-svg-loader` (or `yarn add -D vite-svg-loader`) and ensure `svgLoader()` is included in `plugins: []` in your `vite.config.js/ts`.

• [plugin:vite-svg-loader] [SVGO] Error: Error: No config file found in...

  cause An issue occurred during SVGO processing, potentially due to invalid `svgoConfig` options, especially after upgrading to SVGO v3 in `vite-svg-loader` v4.0.0.
  fix Review your `svgoConfig` in `vite.config.js/ts` and ensure it adheres to the SVGO v3 configuration format. You can also temporarily set `svgo: false` to isolate if the problem is with SVGO configuration.

Warnings

• breaking Version 5.0.0 introduced breaking changes for compatibility with Vite v5. Users upgrading their Vite projects should ensure they also upgrade `vite-svg-loader` to v5.0.0 or higher.
  Fix: Upgrade `vite-svg-loader` to version 5.0.0 or later: `npm install vite-svg-loader@latest` or `yarn add vite-svg-loader@latest`.
• breaking Version 4.0.0 upgraded the underlying SVGO library to SVGO v3. This change might introduce new optimization behaviors or require adjustments to existing `svgoConfig` options.
  Fix: Review your `svgoConfig` options against SVGO v3 documentation if you encounter unexpected SVG output or build errors after upgrading to `vite-svg-loader@4.0.0`.
• breaking Version 5.0.1 changed the package type to 'module', which could have caused issues for CommonJS environments. While version 5.1.0 reverted some internal ESM import changes to improve compatibility, users on 5.0.1 might have encountered CJS import errors.
  Fix: Ensure you are using `vite-svg-loader` version 5.1.0 or newer to avoid potential CommonJS compatibility issues related to package type changes. Prefer ESM `import` statements.
• breaking A high-severity vulnerability (GHSA-xpqw-6gx7-v673 / CVE-2026-29074) in the `svgo` dependency was fixed in version 5.1.1. This vulnerability could potentially affect the security of your build process if unpatched.
  Fix: Immediately upgrade `vite-svg-loader` to version 5.1.1 or higher to patch the high-severity vulnerability: `npm update vite-svg-loader` or `yarn upgrade vite-svg-loader`.
• gotcha TypeScript users must include a type reference for SVG imports to be correctly recognized by the TypeScript compiler. Without it, you may get 'Cannot find module' errors for SVG files.
  Fix: Add `/// <reference types="vite-svg-loader" />` to your `vite-env.d.ts` file or other global declaration file.

Install

• npm install vite-svg-loader npm
• yarn add vite-svg-loader yarn
• pnpm add vite-svg-loader pnpm

Imports

• svgLoader
  wrong:

  const svgLoader = require('vite-svg-loader')

  correct:

  import svgLoader from 'vite-svg-loader'

  The package primarily uses ESM for its main export since v5, favoring 'import' statements. While v5.1.0 reverted some internal ESM changes for compatibility, external plugin usage should still prefer ESM imports.
• MyIcon
  wrong:

  import { MyIcon } from './assets/my-icon.svg'

  correct:

  import MyIcon from './assets/my-icon.svg'

  By default, importing an SVG file will treat it as a default export, representing a Vue component. Do not use named imports.
• iconUrl
  wrong:

  import iconUrl from './assets/my-icon.svg'

  correct:

  import iconUrl from './assets/my-icon.svg?url'

  Use the '?url' suffix to explicitly import the SVG as a data URI or public URL, bypassing the component conversion process.
• SvgRawString
  wrong:

  import { SvgRawString } from './assets/my-icon.svg?raw'

  correct:

  import SvgRawString from './assets/my-icon.svg?raw'

  The '?raw' suffix imports the SVG file content as a plain string. It is a default export, not a named one.
• Type Reference

  /// <reference types="vite-svg-loader" />

  For TypeScript projects, add this line to your `vite-env.d.ts` file (or `tsconfig.json` `types` array) to ensure correct type inference for SVG imports.

Quickstart

Demonstrates how to configure `vite-svg-loader` in `vite.config.ts`, including SVGO customization, and how to import SVGs as both Vue components and URLs in a Vue SFC.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import svgLoader from 'vite-svg-loader';

export default defineConfig({
  plugins: [
    vue(),
    svgLoader({
      svgoConfig: { // Example: customize SVGO options
        multipass: true,
        plugins: ['preset-default', { name: 'removeViewBox', active: false }]
      },
      defaultImport: 'component' // Default, but explicitly set for clarity
    })
  ]
});

// src/App.vue
// <template>
//   <h1>My App</h1>
//   <MyLogo aria-label="Company Logo" />
//   <img :src="imageUrl" alt="SVG as Image" />
// </template>

// <script setup>
// import MyLogo from './assets/logo.svg'; // Imported as Vue component
// import imageUrl from './assets/background.svg?url'; // Imported as URL
// </script>