#SVGR plugin

By default, Rsbuild treats SVG files as static assets. For processing rules, see Static assets.

With the SVGR plugin, Rsbuild supports transforming SVG to React components via SVGR.

#Quick start

#Install plugin

You can install the plugin using the following command:

npm add @rsbuild/plugin-svgr -D

yarn add @rsbuild/plugin-svgr -D

pnpm add @rsbuild/plugin-svgr -D

bun add @rsbuild/plugin-svgr -D

deno add npm:@rsbuild/plugin-svgr -D

#Register plugin

You can register the plugin in the rsbuild.config.ts file:

import { pluginReact } from '@rsbuild/plugin-react';
import { pluginSvgr } from '@rsbuild/plugin-svgr';

export default {
  plugins: [pluginReact(), pluginSvgr()],
};

#Example

#Default usage

After registering the plugin, when you import an SVG in a JavaScript file, if the imported path includes the ?react suffix, Rsbuild will call SVGR to transform the SVG into a React component.

import Logo from './logo.svg?react';

export const App = () => <Logo />;

If the imported path doesn't include the ?react suffix, the SVG will be treated as a normal static asset and you will get a URL string or base64 URL. See Static assets.

import logoURL from './static/logo.svg';

console.log(logoURL); // => "/static/logo.6c12aba3.png"

#Named import

@rsbuild/plugin-svgr supports named imports for ReactComponent when using SVGR. You need to set svgrOptions.exportType to 'named':

pluginSvgr({
  svgrOptions: {
    exportType: 'named',
  },
});

import { ReactComponent as Logo } from './logo.svg';

export const App = () => <Logo />;

@rsbuild/plugin-svgr also supports default imports and mixed imports:

• Enable default imports by setting svgrOptions.exportType to 'default'.
• Enable mixed imports by setting the mixedImport option to use both default and named imports at the same time.

#Options

To customize the compilation behavior of Svgr, use the following options.

• Type:

type PluginSvgrOptions = {
  /**
   * Configure SVGR options.
   */
  svgrOptions?: import('@svgr/core').Config;
  /**
   * Whether to allow the use of default import and named import at the same time.
   * @default false
   */
  mixedImport?: boolean;
};

#svgrOptions

Modifies the options of SVGR, the passed object will be deep merged with the default value. See SVGR - Options for details.

• Type: import('@svgr/core').Config
• Default:

const defaultSvgrOptions = {
  svgo: true,
  svgoConfig: {
    plugins: [
      {
        name: 'preset-default',
        params: {
          overrides: {
            removeViewBox: false,
          },
        },
      },
      'prefixIds',
    ],
  },
};

• Example:

pluginSvgr({
  svgrOptions: {
    svgoConfig: {
      datauri: 'base64',
    },
  },
});

When you set svgoConfig.plugins, the configuration for plugins with the same name is automatically merged. For example, the following configuration will be merged with the built-in preset-default:

pluginSvgr({
  svgrOptions: {
    svgoConfig: {
      plugins: [
        {
          name: 'preset-default',
          params: {
            overrides: {
              cleanupIds: false,
            },
          },
        },
      ],
    },
  },
});

The merged svgoConfig will be:

const mergedSvgoConfig = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: true,
          cleanupIds: false,
        },
      },
    },
    'prefixIds',
  ],
};

#svgrOptions.exportType

Set the export type of SVG React components.

• Type: 'default' | 'named'
• Default: undefined

exportType can be set as:

• default: use default export.
• named: use ReactComponent named export.

For example, set the default export of SVG file as a React component:

pluginSvgr({
  svgrOptions: {
    exportType: 'default',
  },
});

Then import the SVG, you'll get a React component instead of a URL:

import Logo from './logo.svg';

console.log(Logo); // => React Component

At this time, you can also specify the ?url query to import the URL, for example:

import logo from './logo.svg?url';

console.log(logo); // => asset url

#mixedImport

• Type: boolean
• Default: false

Whether to enable mixed import, allowing to use default import and named import at the same time.

Mixed import is usually used with svgrOptions.exportType: 'named', for example:

pluginSvgr({
  mixedImport: true,
  svgrOptions: {
    exportType: 'named',
  },
});

At this time, the imported SVG file will export both URL and the React component:

import logoUrl, { ReactComponent as Logo } from './logo.svg';

console.log(logoUrl); // -> string
console.log(Logo); // -> React component

#Limitations

We recommend using ?react to convert an SVG into a React component rather than relying on mixed imports, which have the following limitations:

1. Increased bundle size: Mixed import causes a single SVG module to be compiled into two types of code (even if some exports are not used), which will increase the bundle size.
2. Slow down compiling: Mixed import will cause extra compilation overhead. Even if the ReactComponent export is not used in the code, the SVG file will still be compiled by SVGR. And SVGR is based on Babel, which has a high performance overhead.

#query

• Type: RegExp
• Default: /react/

Used to custom the query suffix to match SVGR transformation.

For example, if you need to match import paths with the ?svgr suffix:

pluginSvgr({
  query: /svgr/,
});

import Logo from './logo.svg?svgr';

export const App = () => <Logo />;

#exclude

• Type: RuleSetCondition
• Default: undefined

Exclude some SVG files, they will not be transformed by SVGR.

For example, if a project includes a.svg and b.svg, you can add b.svg to exclude:

pluginSvgr({
  svgrOptions: {
    exportType: 'default',
  },
  exclude: /b\.svg/,
});

When imported, a.svg will be transformed into a React component, while b.svg will be treated as a regular static asset:

import component from './a.svg';
import url from './b.svg';

console.log(component); // => React component
console.log(url); // => resource url

#excludeImporter

• Type: RuleSetCondition
• Default: undefined

Exclude some modules, the SVGs imported by these modules will not be transformed by SVGR.

For example, if your project contains page-a/index.ts and page-b/index.ts, you can add page-b to excludeImporter:

pluginSvgr({
  svgrOptions: {
    exportType: 'default',
  },
  excludeImporter: /\/page-b\/index\.ts/,
});

• SVGs referenced in page-a will be transformed to React components:

import Logo from './logo.svg';

console.log(Logo); // => React component

• SVGs referenced in page-b will be treated as static assets:

import url from './logo.svg';

console.log(url); // => Resource url

#Type declaration

When you reference an SVG asset in TypeScript code, TypeScript may prompt that the module is missing a type definition:

TS2307: Cannot find module './logo.svg' or its corresponding type declarations.

To fix this, add type declarations for the SVG assets by creating a src/env.d.ts file and adding the declarations below.

• By default, you can add the following type declarations:

declare module '*.svg' {
  const content: string;
  export default content;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

• If the value of svgrOptions.exportType is 'default', set the type declaration to:

declare module '*.svg' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

• If the value of svgrOptions.exportType is 'named', set the type declaration to:

declare module '*.svg' {
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement>
  >;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

• If the value of svgrOptions.exportType is 'named', and mixedImport is enabled, set the type declaration to:

declare module '*.svg' {
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement>
  >;
  const content: string;
  export default content;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

After adding the type declarations, if the type error still exists, you can try to restart the IDE, or adjust the directory where env.d.ts is located, making sure that TypeScript can correctly identify the type definition.