Motivation

Working with SVG icons in React applications often requires manual setup and maintenance of icon mappings and types.

@fewings/svgr automates this process by:

• Scanning a directory of SVG files
• Generating TypeScript types for your SVGs
• Creating a map of SVG components for easy import
• Optionally creating a ready-to-use Icon component

This allows you to focus on using your SVGs rather than managing the boilerplate code around them.

Installation

# npm
npm install --save-dev @fewings/svgr

# yarn
yarn add -D @fewings/svgr

# pnpm
pnpm add -D @fewings/svgr

Getting Started

There are two ways to use @fewings/svgr:

1. CLI tool: ideal for build scripts and one-time generation
2. Vite plugin: provides automatic watching and rebuilding during development

CLI Usage

The CLI tool lets you generate SVG mappings from your command line or NPM scripts.

# Basic usage
fewings-svgr --svgPath ./public/assets/svg --outDir ./src/Icon

# With component generation
fewings-svgr --svgPath ./public/assets/svg --outDir ./src/Icon --componentName Icon

# With watch mode
fewings-svgr --svgPath ./public/assets/svg --outDir ./src/Icon --watch

Adding to your npm scripts:

"scripts": {
  "build:svgr": "fewings-svgr --svgPath ./public/assets/svg --outDir ./src/Icon --componentName Icon"
}

CLI Options

| Option | Description | Required | Default | | --------------- | ---------------------------------------------------- | -------- | ------------------------------------ | | svgPath | Path to the directory containing SVG files | Yes | - | | outDir | Output directory for generated files | Yes | - | | constName | Name of the generated SVG map constant | No | IconMap | | typeName | Name of the generated TypeScript type | No | IconKeys | | svgImportBase | Base path for SVG imports (if you use absolute path) | No | Auto-generated relative path | | componentName | Name of the generated component | No | No component is generated if omitted | | watch | Watch for changes in the SVG directory | No | false |

Vite Plugin Usage

The Vite plugin automatically watches for changes to your SVG files during development.

// vite.config.ts
import { defineConfig } from "vite";
import { fewingsSvgrVitePlugin } from "@fewings/svgr";
import svgr from "vite-plugin-svgr";

export default defineConfig({
  plugins: [
    svgr(), // Standard SVGR plugin for importing SVGs as React components
    fewingsSvgrVitePlugin({
      svgPath: "./public/assets/svg",
      outDir: "./src/Icon",
      componentName: "Icon",
      importBase: "@assets/svg", // Optional: base path for SVG imports
    }),
  ],
});

Plugin Options

| Option | Description | Required | Default | | --------------- | ------------------------------------------ | -------- | ------------------------------------ | | svgPath | Path to the directory containing SVG files | Yes | - | | outDir | Output directory for generated files | Yes | - | | constName | Name of the generated SVG map constant | No | IconMap | | typeName | Name of the generated TypeScript type | No | IconKeys | | svgImportBase | Base path for SVG imports | No | Auto-generated relative path | | componentName | Name of the generated component | No | No component is generated if omitted |

Using the Generated Code

After @fewings/svgr has processed your SVG files, it will generate:

1. A map of all your SVG components
2. TypeScript types for type safety
3. Optionally, an Icon component ready to use in your app

Example Usage:

// Using the generated Icon component
import { Icon } from "./src/Icon/Icon";

function App() {
  return (
    <div>
      <Icon name="arrow-right" width={24} height={24} />
      <Icon name="home" color="#ff0000" />
    </div>
  );
}

// Using the generated map directly
import { IconMap, IconKeys } from "./src/Icon/IconMap";

function CustomIcon({
  name,
  ...props
}: { name: IconKeys } & React.SVGProps<SVGSVGElement>) {
  const SvgComponent = IconMap[name];
  return <SvgComponent {...props} />;
}

Contributing

Contributions are welcome! If you have suggestions, bug reports, or feature requests, please open an issue or submit a pull request on the GitHub repository.