or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-svgr--webpack

SVGR webpack loader that transforms SVG files into React components during the build process.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@svgr/webpack@8.1.x

To install, run

npx @tessl/cli install tessl/npm-svgr--webpack@8.1.0

@svgr/webpack

@svgr/webpack is a webpack loader that transforms SVG files into React components during the build process. It integrates the SVGR transformation system with webpack's module loading, allowing developers to import SVG files as React components with full TypeScript support and extensive configuration options.

Package Information

Package Name: @svgr/webpack
Package Type: npm
Language: TypeScript
Installation: npm install @svgr/webpack --save-dev

Core Imports

The package exports a default webpack loader function:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};

Basic Usage

// webpack.config.js - Basic SVG to React component transformation
{
  test: /\.svg$/,
  use: ['@svgr/webpack'],
}

// In your React code
import Star from './star.svg';

const App = () => (
  <div>
    <Star />
  </div>
);

Architecture

@svgr/webpack is built on several key components:

Webpack Loader Interface: Integrates with webpack's module loading system using the standard loader API
SVGR Core Integration: Uses @svgr/core's transform function for SVG to JSX conversion
Babel Pipeline: Optional Babel transformation for React/TypeScript code generation
Export Detection: Automatically detects and handles existing module exports from other loaders
Configuration System: Supports all SVGR configuration options plus webpack-specific settings

Capabilities

Webpack Loader

Main webpack loader function that processes SVG files and transforms them into React components.

/**
 * SVGR webpack loader function
 * @param contents - SVG file contents as string
 * @returns void (uses webpack's callback system)
 */
function svgrLoader(
  this: webpack.LoaderContext<LoaderOptions>,
  contents: string,
): void;

interface LoaderOptions extends Config {
  babel?: boolean;
}

Configuration Options

Complete configuration interface extending SVGR core options with webpack-specific settings.

interface Config {
  ref?: boolean;
  titleProp?: boolean;
  descProp?: boolean;
  expandProps?: boolean | 'start' | 'end';
  dimensions?: boolean;
  icon?: boolean | string | number;
  native?: boolean;
  svgProps?: {
    [key: string]: string;
  };
  replaceAttrValues?: {
    [key: string]: string;
  };
  runtimeConfig?: boolean;
  typescript?: boolean;
  prettier?: boolean;
  prettierConfig?: PrettierOptions;
  svgo?: boolean;
  svgoConfig?: SvgoConfig;
  configFile?: string;
  template?: TransformOptions['template'];
  memo?: boolean;
  exportType?: 'named' | 'default';
  namedExport?: string;
  jsxRuntime?: 'classic' | 'classic-preact' | 'automatic';
  jsxRuntimeImport?: {
    source: string;
    namespace?: string;
    specifiers?: string[];
    defaultSpecifier?: string;
  };
  jsx?: {
    babelConfig?: BabelTransformOptions;
  };
}

Usage Examples:

// Basic configuration with options
{
  test: /\.svg$/,
  use: [
    {
      loader: '@svgr/webpack',
      options: {
        native: true,
        typescript: true,
        svgo: false,
      },
    },
  ],
}

// With custom SVG props
{
  test: /\.svg$/,
  use: [
    {
      loader: '@svgr/webpack',
      options: {
        svgProps: { role: 'img' },
        replaceAttrValues: { '#000': 'currentColor' },
      },
    },
  ],
}

Loader Integration with Other Loaders

Seamless integration with other webpack loaders like url-loader for dual-purpose SVG handling.

// Usage with url-loader for both component and URL exports
{
  test: /\.svg$/,
  use: ['@svgr/webpack', 'url-loader'],
}

Usage Example:

// Dual import - both as React component and as URL
import starUrl, { ReactComponent as Star } from './star.svg';

const App = () => (
  <div>
    <img src={starUrl} alt="star" />
    <Star />
  </div>
);

Custom Babel Configuration

Disable built-in Babel transformation to use custom Babel configuration.

// Webpack configuration with custom Babel
{
  test: /\.svg$/,
  use: [
    {
      loader: 'babel-loader',
      options: {
        presets: ['preact', 'env'],
      },
    },
    {
      loader: '@svgr/webpack',
      options: { babel: false },
    }
  ],
}

Rule-Based Configuration

Advanced webpack configuration for different file contexts using Rule.issuer.

// Different handling for JavaScript vs CSS imports
[
  {
    test: /\.svg(\?v=\d+\.\d+\.\d+)?$/,
    issuer: /\.[jt]sx?$/,
    use: ['babel-loader', '@svgr/webpack', 'url-loader'],
  },
  {
    test: /\.svg(\?v=\d+\.\d+\.\d+)?$/,
    loader: 'url-loader',
  },
]

Types

LoaderOptions

Configuration options specific to the webpack loader.

interface LoaderOptions extends Config {
  /** Enable/disable Babel transformation (default: true) */
  babel?: boolean;
}

Config

Complete SVGR configuration interface with all available options.

interface Config {
  ref?: boolean;
  titleProp?: boolean;
  descProp?: boolean;
  expandProps?: boolean | 'start' | 'end';
  dimensions?: boolean;
  icon?: boolean | string | number;
  native?: boolean;
  svgProps?: {
    [key: string]: string;
  };
  replaceAttrValues?: {
    [key: string]: string;
  };
  runtimeConfig?: boolean;
  typescript?: boolean;
  prettier?: boolean;
  prettierConfig?: PrettierOptions;
  svgo?: boolean;
  svgoConfig?: SvgoConfig;
  configFile?: string;
  template?: TransformOptions['template'];
  memo?: boolean;
  exportType?: 'named' | 'default';
  namedExport?: string;
  jsxRuntime?: 'classic' | 'classic-preact' | 'automatic';
  jsxRuntimeImport?: {
    source: string;
    namespace?: string;
    specifiers?: string[];
    defaultSpecifier?: string;
  };
  jsx?: {
    babelConfig?: BabelTransformOptions;
  };
}

State

Processing state information passed to SVGR transformation plugins.

interface State {
  filePath?: string;
  componentName: string;
  caller?: {
    name?: string;
    previousExport?: string | null;
    defaultPlugins?: ConfigPlugin[];
  };
}

External Types

External type definitions from dependencies used in the API.

// From Prettier
interface PrettierOptions {
  [key: string]: any;
}

// From SVGO
interface SvgoConfig {
  plugins?: string[] | object[];
  [key: string]: any;
}

// From @svgr/babel-preset
interface TransformOptions {
  template?: (variables: any, context: any) => any;
  [key: string]: any;
}

// From @babel/core
interface BabelTransformOptions {
  presets?: any[];
  plugins?: any[];
  [key: string]: any;
}

// From @svgr/core
interface ConfigPlugin {
  (code: string, config: Config, state: State): string;
}

Webpack Types

Webpack-specific type definitions used by the loader.

// Simplified webpack LoaderContext interface (from webpack)
namespace webpack {
  interface LoaderContext<TOptions> {
    cacheable(): void;
    async(): (err?: Error, result?: string) => void;
    getOptions(): TOptions;
    resourcePath: string;
    fs: {
      readFile(path: string, callback: (err: Error | null, data?: Buffer) => void): void;
    };
  }
}

Export Behavior

The loader automatically detects and handles different export scenarios:

Standalone Usage: Exports React component as default export
With Other Loaders: Exports React component as named export (default: ReactComponent)
Custom Named Export: Configurable via namedExport option
Export Type Control: Force named export via exportType: 'named'

Error Handling

The loader handles errors through webpack's standard callback mechanism:

Babel Transformation Errors: Throws "Error while transforming using Babel"
File System Errors: Propagated through webpack's error callback
SVGR Transform Errors: Passed through from @svgr/core transformation process

Advanced Configuration

TypeScript Integration

{
  test: /\.svg$/,
  use: [
    {
      loader: '@svgr/webpack',
      options: {
        typescript: true,
        prettier: false,
        svgo: true,
        svgoConfig: {
          plugins: ['preset-default', 'removeViewBox'],
        },
      },
    },
  ],
}

Custom Template Function

{
  test: /\.svg$/,
  use: [
    {
      loader: '@svgr/webpack',
      options: {
        template: (variables, { tpl }) => {
          return tpl`
            ${variables.imports};
            ${variables.interfaces};
            
            const ${variables.componentName} = (${variables.props}) => (
              ${variables.jsx}
            );
            
            export default ${variables.componentName};
          `;
        },
      },
    },
  ],
}