{"id":13691,"library":"nuxt-svgo","title":"Nuxt SVGO","description":"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.","status":"active","version":"4.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/cpsoinos/nuxt-svgo","tags":["javascript","nuxt","nuxt-module","nuxtjs","svg","svgo","vue","typescript"],"install":[{"cmd":"npm install nuxt-svgo","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-svgo","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-svgo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for SVG optimization.","package":"svgo-loader","optional":false},{"reason":"Runtime for Vue components, required by Nuxt.","package":"vue","optional":false},{"reason":"Required by Nuxt's build process (webpack/vite) to load Vue components, including SVGs processed into components.","package":"vue-loader","optional":false},{"reason":"Specifically handles the transformation of SVG files into Vue components.","package":"vue-svg-loader","optional":false}],"imports":[{"note":"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.","wrong":"const IconName = require('~/assets/icons/icon-name.svg')","symbol":"IconName","correct":"import IconName from '~/assets/icons/icon-name.svg'"},{"note":"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.","wrong":"import SvgoName from 'SvgoName'","symbol":"SvgoName","correct":""},{"note":"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.","wrong":"import defineNuxtConfig from 'nuxt/config'","symbol":"defineNuxtConfig","correct":"import { defineNuxtConfig } from 'nuxt'; modules: ['nuxt-svgo']"}],"quickstart":{"code":"\n\n\n\n\n\n\n\n\n\n","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"To 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`.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"When 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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., ``.","message":"By 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`.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.2.0"},{"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 ``.","message":"Disabling 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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'3':8,48 '4.2.6':25 'addit':44 'address':112 'allow':79 'applic':19 'asset':127 'auto':93 'auto-import':92 'bundl':115 'cadenc':32 'capabl':73 'combin':69 'compat':36 'compon':21,77,88,105,141 'concern':113 'consist':30 'control':108 'current':22 'custom':102 'declar':54 'design':10 'develop':80 'differenti':65 'direct':16,85 'ecosystem':145 'effect':111 'featur':43 'file':15,84,133 'flexibl':98 'focus':34 'generat':55 'global':109 'icon':122 'import':82,94,103 'integr':12 'javascript':146 'key':64 'larg':119 'latest':39 'layer':49 'leverag':90 'librari':27 'lie':66 'maintain':28 'manag':128 'mechan':95 'modul':9,124,150 'monorepo':41 'number':120 'nuxt':1,3,7,40,47,75,144,147,149 'nuxt-modul':148 'nuxtj':151 'offer':97 'optim':13,72,135 'option':100 'path':104 'period':62 'prefix':106 'primarili':33 'raw':131 'readi':137 'ready-to-us':136 'registr':110 'releas':31 'roll':60 'seamless':68 'simplifi':125 'size':116 'support':50 'svg':14,83,126,132,152 'svgo':2,4,70,153 'system':78 'transform':130 'type':53 'typescript':155 'updat':42 'use':139 'v4.1.0':58 'v4.2.0':51 'version':24 'vite':57 'vue':18,87,140,154 'within':142","created_at":"2026-04-20T01:55:48.319326+00:00","updated_at":"2026-04-20T01:55:48.319326+00:00","problems":[{"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.","cause":"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.","error":"Module not found: Can't resolve '~/assets/icon-home.svg'"},{"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.","cause":"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.","error":"Property 'SvgoIconName' does not exist on type 'GlobalComponents'."},{"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.","cause":"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`.","error":"SVG content is not rendered or looks incorrect (e.g., missing styles, broken elements)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/cpsoinos/nuxt-svgo","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/nuxt-svgo","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}