nuxt-svgo

library4.2.6jsnpmunverified

Nuxt SVGO is a Nuxt 3 module designed to integrate optimized SVG files directly into Vue applications as components. Currently at version 4.2.6, the library maintains a consistent release cadence, primarily focusing on compatibility with the latest Nuxt monorepo updates. Feature additions, such as Nuxt 3 layers support (v4.2.0) and type declaration generation for Vite (v4.1.0), are rolled out periodically. Its key differentiation lies in seamlessly combining SVGO's optimization capabilities with Nuxt's component system, allowing developers to import `.svg` files directly as Vue components or leverage an auto-import mechanism. It offers flexibility through options for custom import paths, component prefixes, and controlling global registration, effectively addressing concerns about bundle size with a large number of icons. This module simplifies SVG asset management by transforming raw SVG files into optimized, ready-to-use Vue components within the Nuxt ecosystem.

web-framework

npm install nuxt-svgo

github ↗package ↗

INSTALL

IMPORT

SIG · NUXT-SVGO

nuxt-svgo

web-frameworkjavascriptv4.2.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IconName

✓ import IconName from '~/assets/icons/icon-name.svg'

✗ const IconName = require('~/assets/icons/icon-name.svg')

For direct imports, the component name is derived from the import variable. Nuxt 3 is ESM-first, so `require()` is incorrect. This pattern typically requires `svgo.autoImportPath` to be `false` or careful pathing.

SvgoName

✓ <template><SvgoName /></template>

✗ import SvgoName from 'SvgoName'

This pattern is for auto-imported SVG components. The component name (`SvgoName` or `svgo-name`) is derived from `svgo.componentPrefix` (default 'Svgo') and the SVG filename (e.g., `home.svg` becomes `SvgoHome`). No explicit `import` statement is needed in the script section as it's globally registered or tree-shaken by Nuxt/Vite.

defineNuxtConfig

✓ import { defineNuxtConfig } from 'nuxt'; modules: ['nuxt-svgo']

✗ import defineNuxtConfig from 'nuxt/config'

This is the standard way to configure Nuxt modules in `nuxt.config.ts`. Ensure `'nuxt-svgo'` is added to the `modules` array to enable the plugin.

Demonstrates how to configure nuxt-svgo and use both direct SVG file imports as Vue components, and auto-imported SVG components (Vite-style) in a Nuxt 3 application, showing different sizing options and requiring example SVG files.

<script setup lang="ts"> import { defineNuxtConfig } from 'nuxt' export default defineNuxtConfig({ modules: ['nuxt-svgo'], svgo: { autoImportPath: './assets/icons/', // Default path for auto-import componentPrefix: 'Svgo', // Default prefix for auto-imported components global: true, // Register components globally by default }, }) </script>  <template> <div class="p-8 font-sans"> <h1 class="text-2xl font-bold mb-4">Nuxt SVGO Demo</h1> <div class="flex items-center space-x-4 mb-4"> <p>Direct Import:</p>  <IconHome class="text-red-500 w-8 h-8" /> <IconHome class="text-blue-500 w-12 h-12" :fontControlled="false" /> </div> <div class="flex items-center space-x-4"> <p>Auto-Import (Vite style):</p>  <SvgoStar class="text-green-500 w-10 h-10" /> <svgo-star class="text-yellow-500 w-14 h-14" /> </div> </div> </template> <script setup lang="ts"> // For direct import, assuming '~/assets/icons/home.svg' exists import IconHome from '~/assets/icons/home.svg'; // For auto-import (e.g., SvgoStar), no explicit import is needed in the script. // It's globally registered or tree-shaken by Nuxt/Vite based on config. </script> <style> /* Add basic tailwind-like classes for demonstration if not using actual Tailwind */ .p-8 { padding: 2rem; } .font-sans { font-family: ui-sans-serif, system-ui, sans-serif; } .text-2xl { font-size: 1.5rem; line-height: 2rem; } .font-bold { font-weight: 700; } .mb-4 { margin-bottom: 1rem; } .flex { display: flex; } .items-center { align-items: center; } .space-x-4 > :not([hidden]) ~ :not([hidden]) { margin-left: 1rem; } .w-8 { width: 2rem; } .h-8 { height: 2rem; } .w-12 { width: 3rem; } .h-12 { height: 3rem; } .w-10 { width: 2.5rem; } .h-10 { height: 2.5rem; } .w-14 { width: 3.5rem; } .h-14 { height: 3.5rem; } .text-red-500 { color: #ef4444; } .text-blue-500 { color: #3b82f6; } .text-green-500 { color: #22c55e; } .text-yellow-500 { color: #facc15; } </style>

Debug

Known issues

gotchaTo function correctly, `nuxt-svgo` relies on several peer dependencies like `svgo-loader`, `vue`, `vue-loader`, and `vue-svg-loader`. These must be explicitly installed alongside `nuxt-svgo`.

fix

Ensure all peer dependencies listed in `package.json` (or the installation instructions) are installed, e.g., `npm install svgo-loader vue vue-loader vue-svg-loader`.

affects: >=4.0.0

breakingWhen using `svgo.global: false`, icons are not globally registered. This is beneficial for tree-shaking and smaller bundles, but means you cannot use auto-imported components directly in templates without explicit local imports or component registration, requiring a different usage pattern than the default global behavior.

fix

If `global: false` is set, either manually import each SVG component you wish to use (`import MyIcon from '~/assets/icons/my-icon.svg'`) in your script setup, or ensure your build setup is correctly tree-shaking and importing components as needed by Nuxt/Vite without explicit global registration.

affects: >=4.0.0

gotchaBy default, the `fontControlled` prop on SVG components is `true`, meaning the `font-size` CSS property will control the SVG's `width` and `height`. If you want to explicitly set `width` and `height` using CSS classes or inline styles, you must set `fontControlled` to `false`.

fix

Add `:fontControlled="false"` to your SVG component when you intend to manage its dimensions using `width`, `height`, or other explicit sizing CSS properties, e.g., `<IconHome class="w-5 h-5" :fontControlled="false" />`.

affects: >=4.0.0

breakingVersion 4.2.0 introduced support for Nuxt 3 Layers. While this is a feature, it means that project structures leveraging Nuxt Layers might need to confirm `nuxt-svgo`'s configuration and asset resolution behavior, especially regarding `autoImportPath` in a multi-layer setup.

fix

Review your `svgo.autoImportPath` configuration in relation to your Nuxt Layers setup. Ensure the paths correctly resolve to the desired SVG assets within your layers or extend configurations where necessary.

affects: >=4.2.0

gotchaDisabling auto-import by setting `svgo.autoImportPath: false` means that SVG files in the specified path will no longer be automatically registered as components. This necessitates explicit imports for every SVG you wish to use.

fix

If `autoImportPath` is `false`, you must explicitly `import` each SVG file as a Vue component in your script section, e.g., `import MySvg from '~/assets/my-svg.svg'`. Ensure your component templates use the imported name `<MySvg />`.

affects: >=4.0.0

Errors

Common errors & fixes

Module not found: Can't resolve '~/assets/icon-home.svg'

The SVG file path is incorrect, the file doesn't exist at the specified location, or a custom `svgo.autoImportPath` is configured, conflicting with direct import attempts.

fix

Verify the exact path to your SVG file. If using direct imports, ensure `svgo.autoImportPath` is not set in a way that prevents resolution, or use the auto-import feature for SVGs in the designated path. Check file existence and correct casing.

Property 'SvgoIconName' does not exist on type 'GlobalComponents'.

This TypeScript error occurs when an auto-imported SVG component (e.g., `SvgoIconName`) is used in a template, but the TypeScript compiler hasn't picked up its global type declaration. This can happen if types aren't generated/cached or if `svgo.global: false` is used without explicit imports.

fix

Restart your Nuxt development server to regenerate types. Ensure `svgo.global` is not `false` if you intend to use auto-import without explicit script imports. If `global: false`, you must explicitly import the component in your script block, and potentially declare module types for `.svg` files if not automatically handled.

SVG content is not rendered or looks incorrect (e.g., missing styles, broken elements).

SVGO's optimization process might have removed essential attributes or styles from the SVG, or your CSS is overriding intended SVG styling due to `fontControlled` being `true`.

fix

Configure SVGO options in your `nuxt.config.ts` (`svgo.svgoConfig`) to preserve necessary attributes or styles. If using custom styles, ensure `:fontControlled="false"` is set on the component. Inspect the rendered SVG in developer tools to see what attributes are missing or overridden.

Upgrade

Version history

4.2.6latest on npm

Audit

Dependencies

svgo-loaderrequiredCore dependency for SVG optimization.

vuerequiredRuntime for Vue components, required by Nuxt.

vue-loaderrequiredRequired by Nuxt's build process (webpack/vite) to load Vue components, including SVGs processed into components.

vue-svg-loaderrequiredSpecifically handles the transformation of SVG files into Vue components.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cpsoinos/nuxt-svgo ↗

packagehttps://www.npmjs.com/package/nuxt-svgo ↗