Vite Plugin: React Rich SVG
Seamless SVG loader with versatile import options (see demo page)
# Description
A vite plugin that handles SVG loading with zero-config effort.
It handles loading raw (html string), inline data uri (`data:svg+xml,...`) and SVGR Component (with easily usable SVGO options) imports easily!
This plugin is heavily inspired by [vite-svg-loader](https://github.com/jpkleemans/vite-svg-loader), which is an SVG loading Vite plugin for Vue. It is one of my favourites. Thanks to everyone contributed to it! 💜
# How to use?
1. Use your favorite package manager to install as dependency
```
npm install vite-plugin-react-rich-svg --save-dev
```
2. Include it in your `vite.config.ts`
```ts
import richSvg from "vite-plugin-react-rich-svg";
export default defineConfig({
plugins: [react(), richSvg()],
});
```
3. If you're using Typescript, you might want to include the typings under `vite-env.d.ts`:
```tsx
// Caveat: referencing our plugin first will ensure vite types do not overlap
///
///
```
4. Start importing your SVGs! Happy coding!
```ts
// Raw string import
import viteLogoRaw from "./assets/vite.svg?raw";
// Data URL import
import viteLogoDataURL from "./assets/vite.svg?url";
// Base64 Encoded import
import viteLogoBase64 from "./assets/vite.svg?base64";
// SVGR Component import
import ViteLogoComponent from "./assets/vite.svg?component";
// Default import, not handled by our plugin
import viteLogo from "./assets/vite.svg";
```
# Plugin Configurations
## `include` option
Acts as a whitelist predicate for the files you want to be processed.
```ts
richSvg({
include: (path) => /.*\.icon\.svg$/.test(path),
// ^ This config will only process files that look like:
// ...chevron-right.icon.svg?raw
// ...chevron-left.icon.svg?component
// ...home.icon.svg?url
}),
```
## `exclude` option
Acts as a blacklist predicate for the files you want to be ignored.
```ts
richSvg({
exclude: (path) => /.*\.ignore\.svg$/.test(path),
// ^ This config will ignore files that look like:
// ...my-illustration.ignore.svg?raw
// ...my-illustration.ignore.svg?component
// ...my-illustration.ignore.svg?url
}),
```
## `componentLoaderOptions` option
- `svgrConfig` = Options used while running SVGR on the original svg code/asset (See [SVGR Options](https://react-svgr.com/docs/options/))
- `oxcConfig` = Options passed to Vite's Oxc transform when generating JavaScript from the SVGR output (See [Vite's `transformWithOxc` API](https://vite.dev/guide/api-javascript.html#transformwithoxc))
```ts
richSvg({
componentLoaderOptions: {
svgrConfig: {
ref: true,
memo: true,
},
// ^ This config will make it load component svg imports loads with forwardedRef & memo wrapped
oxcConfig: {
jsx: {
runtime: "automatic",
},
},
// ^ These options are passed to Oxc after SVGR generates the component code
},
}),
```
## `rawLoaderOptions` option
- `svgoEnabled` = Enables SVGO optimizations
- `svgoConfig` = Options used while running SVGO optimizations on the original SVG asset (See [SVGO Options](https://github.com/svg/svgo#configuration))
```ts
richSvg({
rawLoaderOptions: {
svgoEnabled: true,
svgoConfig: {},
},
}),
```
## `base64LoaderOptions` option
- `svgoEnabled` = Enables SVGO optimizations
- `svgoConfig` = Options used while running SVGO optimizations on the original SVG asset (See [SVGO Options](https://github.com/svg/svgo#configuration))
```ts
richSvg({
base64LoaderOptions: {
svgoEnabled: true,
svgoConfig: {},
},
}),
```
## `urlLoaderOptions` option
- `svgoEnabled` = Enables SVGO optimizations
- `svgoConfig` = Options used while running SVGO optimizations on the original SVG asset (See [SVGO Options](https://github.com/svg/svgo#configuration))
```ts
richSvg({
urlLoaderOptions: {
svgoEnabled: true,
svgoConfig: {},
},
}),
```
# SVGO, Prettier & Other SVGR Plugins
SVGO and Prettier are supported out of the box. Just mark them in the svgrConfig and they'll start working.
You can also include your own SVGR plugins as you desire!
```ts
import myCustomSvgrPlugin from "my-custom-svgr-plugin";
import myCustomSvgoPlugin from "my-custom-svgo-plugin";
import myCustomPrettierPlugin from "my-custom-prettier-plugin";
richSvg({
componentLoaderOptions: {
svgrConfig: {
svgo: true,
prettier: true,
prettierConfig: {
plugins: ["prettier-plugin-foo"]
},
plugins: [myCustomSvgrPlugin],
},
},
rawLoaderOptions: {
svgoEnabled: true,
svgoConfig: {
plugins: [myCustomSvgoPlugin]
}
},
base64LoaderOptions: {
svgoEnabled: true,
svgoConfig: {
plugins: [myCustomSvgoPlugin]
}
},
urlLoaderOptions: {
svgoEnabled: true,
svgoConfig: {
plugins: [myCustomSvgoPlugin]
}
}
}),
```
## License
© 2024 Taha Anılcan Metinyurt (iGoodie)
For any part of this work for which the license is applicable, this work is licensed under the [Attribution-ShareAlike 4.0 International](http://creativecommons.org/licenses/by-sa/4.0/) license. (See LICENSE).
