astro-svg-lens focuses on developer visibility. It does not replace Astro's official SVG component support; it helps you find the SVG asset you already have and copy the import you need.

Features

• Scan SVG files from configurable project directories
• Preview optimized SVGs in the Astro Dev Toolbar (scripts and event handlers are stripped before rendering)
• Search SVGs by file name or project path
• Browse SVGs grouped by directory
• Copy component imports, raw imports, and project-relative paths — public/ assets get URL usage instead
• Refresh automatically when SVG files are added, changed, or removed
• Keep SVG rendering behavior in Astro's official SVG pipeline

Installation

Add the integration with Astro's setup command:

pnpm astro add astro-svg-lens

Or install it manually:

pnpm add -D astro-svg-lens

npm install -D astro-svg-lens

yarn add -D astro-svg-lens

Usage

Add the integration to your Astro config:

// astro.config.mjs
import { defineConfig } from "astro/config";
import svgLens from "astro-svg-lens";

export default defineConfig({
  integrations: [
    svgLens({
      dirs: ["src", "public"],
    }),
  ],
});

Start Astro in dev mode and open the Astro Dev Toolbar. The SVG Lens panel will show matching SVG files.

Options

interface SvgLensOptions {
  /**
   * Directories to scan, relative to the Astro project root.
   * Defaults to ["src", "public"].
   */
  dirs?: string[];

  /**
   * Enable the Astro Dev Toolbar app.
   * Defaults to true.
   */
  toolbar?: boolean;
}

Examples

Scan common source and public asset folders:

svgLens({
  dirs: ["src/assets", "src/icons", "public"],
});

Disable the toolbar while keeping the integration installed:

svgLens({
  toolbar: false,
});

What It Copies

For an SVG at src/icons/home.svg, SVG Lens copies root-absolute import snippets that work in any Astro project without path aliases:

import HomeIcon from "/src/icons/home.svg";
import homeSvg from "/src/icons/home.svg?raw";

The component import uses Astro's built-in SVG component support and can be rendered in .astro and MDX files. The ?raw import uses Astro's underlying Vite asset handling when the SVG source string is needed. Astro SVG components are not directly renderable inside UI framework components such as React or Svelte.

Files under public/ are static assets and cannot be imported as modules, so SVG Lens offers URL-based usage for them instead. For public/logo.svg:

/logo.svg
<img src="/logo.svg" alt="logo" />

It also exposes the project-relative path:

src/icons/home.svg

What This Package Does Not Do

astro-svg-lens does not transform SVG files into components itself.

Modern Astro already supports importing SVG files as components, so this package intentionally stays focused on discovery: scanning, previewing, searching, and copying import snippets from the Dev Toolbar.

License

MIT