# rollup-plugin-purge-icons
> Rollup plugin for PurgeIcons
Latest version **0.10.0** (published 2023-11-18) · MIT license · 0 weekly downloads
## Install
```sh
npm install rollup-plugin-purge-icons
pnpm add rollup-plugin-purge-icons
yarn add rollup-plugin-purge-icons
bun add rollup-plugin-purge-icons
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities.
Warnings: low downloads; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.10.0 |
| Published | 2023-11-18 |
| First published | 2020-08-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 12 |
| Dependencies | 2 |
| Unpacked size | 8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 233 |
| Author | Anthony Fu |
| Maintainers | antfu |
| Keywords | rollup-plugin, purge-icons |
## Links
- npm: https://www.npmjs.com/package/rollup-plugin-purge-icons
- Repository: https://github.com/antfu/purge-icons
- Homepage: https://github.com/antfu/purge-icons/tree/master/packages/rollup-plugin-purge-icons#readme
- Issues: https://github.com/antfu/purge-icons/issues
- npm.io page: https://npm.io/package/rollup-plugin-purge-icons
## Dependencies (2)
- [@purge-icons/core](https://npm.io/package/@purge-icons/core.md) ^0.10.0
- [@purge-icons/generated](https://npm.io/package/@purge-icons/generated.md) ^0.10.0
## Alternatives
- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads
- [@react-md/material-icons](https://npm.io/package/@react-md/material-icons.md) — 1.6K weekly downloads
## Recent versions
- 0.10.0 (latest) — 2023-11-18
- 0.9.1 — 2022-09-20
- 0.9.0 — 2022-08-09
- 0.8.1 — 2022-02-28
- 0.8.0 — 2022-02-26
- 0.7.0 — 2021-02-17
- 0.6.0 — 2021-01-24
- 0.5.2 — 2021-01-19
- 0.5.1 — 2021-01-13
- 0.5.0 — 2021-01-04
- 0.4.5 — 2020-11-05
- 0.4.4 — 2020-10-15
- 0.4.2 — 2020-09-28
- 0.4.1 — 2020-09-16
- 0.4.0 — 2020-08-16
- … 3 more at https://npm.io/package/rollup-plugin-purge-icons/versions
## README
It's now recommended to use [UnoCSS Icons](https://github.com/unocss/unocss/tree/main/packages/preset-icons), [unplugin-icons](https://github.com/antfu/unplugin-icons) or [Iconify Icon Components](https://docs.iconify.design/icon-components/components/) instead of this approach.
----
PurgeIcons
Bundles only the icons you use
Think about TailwindCSS + PurgeCSS, but for Icons.
## Intro
**PurgeIcons** is heavily inspired from [PurgeCSS](https://purgecss.com/). It analyzes your source code or dist files, extracting the icon names you used, and then bundle the icons' data (SVGs) into your code.
**You will only get icons you need. No extra bandwidth, no unused icons, no compromise.**
Underneath, it's powered by [**Iconify**](https://iconify.design), which you get access to 80+ popular open source iconsets with over 5,000 icons to choice, including ***Material Design Icons***, ***Font Awesome***, ***Octicon*** and even ***Emojis***!
Browser the icon sets in [Icônes](https://icones.netlify.app/) or [Iconify](https://iconify.design/icon-sets/).
## Usage
Just like what you used to do for Iconify.
```html
```
Or even dynamic
```js
const span = createElement('span')
span.class = 'iconify'
span.data.icon = isDark ? 'carbon:moon' : 'carbon:sun'
// DON'T, PurgeIcons won't extract them correct.
// add them to `included` to be always bundled if you really want this
span.data.icon = `carbon:${isDark ? 'moon' : 'sun'}`
```
## Install
**PurgeIcons** is designed to be framework independent, but using framework plugins is the most recommended way to get started. Check out the supported frameworks in the following list. We are trying to make more frameworks able to use PurgeIcons out-of-box. Pull requests are great welcome!
### Official Plugins
| | Plugin | Example | Template |
| --- | --- | --- | --- |
| Vite | [vite-plugin-purge-icons](./packages/vite-plugin-purge-icons) | [Example](./examples/vite) | [Vitesse](https://github.com/antfu/vitesse) |
| Nuxt | [nuxt-plugin-purge-module](./packages/nuxt-plugin-purge-module) | [Example](./examples/nuxt) | |
| Vue CLI | Coming... | | |
| Gridsome | Coming... | | |
| Parcel | Coming... | | |
| Webpack | [purge-icons-webpack-plugin](./packages/purge-icons-webpack-plugin) | | |
| Rollup | [rollup-plugin-purge-icons](./packages/rollup-plugin-purge-icons) | | |
## Command Line Interface
> The CLI is still working in progress and the design is not yet finalized.
You can either install PurgeIcons as a dev dependency and use the CLI with npx or you can also install PurgeIcons globally:
```bash
npm i -g purge-icons
```
Scan the all the html file and geneted a `mjs` bundle
```bash
purge-icons --content 'src/*.html' --format mjs --output output.js
```
From multiple sources and use args shorthands, `format` can be auto inferred from the `output` option
```bash
purge-icons -c 'index.html,src/**/*.vue' -o output.ts
```
Or export plain json file for other tools to process
```bash
purge-icons -c index.html -o output.json
```
See more options by
```bash
purge-icons --help
```
## Programmatic API
> Programmatic API is still working in progress as well.
For programmatic use only, you can use `@purge-icons/core`
```bash
npm i -D @purge-icons/core
```
```ts
import { PurgeIconsOptions, PurgeIcons } from '@purge-icons/core'
const code = await PurgeIcons({
// globs for searching source file to analyze
content: [
'**/*.html',
'**/*.js',
'**/*.vue', // scan for .vue file as well
],
// whitelist for icons that might be used dynamically
included: [
'mdi:account-circle-outline', // from Material Design Icons
'fa:camera', // from Font Awesome 4
],
format: 'mjs'
})
// code is generated with inlined icons's data, bundle the file and it's done.
fs.promises.writeFiles('./icons.mjs', code, 'utf-8')
```
### Options
```ts
export interface PurgeIconsOptions {
content?: (string | RawContent)[]
included?: string[]
extractors?: Extractor[]
iconSource?: IconSource // default to 'auto'
}
```
## How It Works
[**Iconify**](https://iconify.design) is an icon framework that provide an unified syntax to use icons from its [huge collections](https://iconify.design/icon-sets/) on-demanded. Each icon set has a id as the prefix of for its icons. For example:
```html
```
Iconify achieve that by building up a API service that only send the icons you need. It provides a great flexibility that you can try with different design style and without to worry about including a large amount of unused icons that eat up your bandwidth and slow down your page load.
However, the downside of API querying is that the icons won't be available on the first meaningful paint and your app will be heavy relied on the API servers' status and so its accessability for your users. Iconify also provides the [offline solution by implementing frameworks components](https://docs.iconify.design/implementations/#components). In that way, you would need to manually import every icon you use.
Thus, PurgeIcons was born. By scanning your code, it generates [bundles](https://docs.iconify.design/sources/bundles/) for Iconify and load them synchronously. You can use icons in the exact same way as you would with the API based solution.
## TODO
- CLI output
- Better caching
- Plugins for frameworks (Vue CLI, Nuxt.js, Next.js, etc.) PR welcome!
- Font-based icons (Javascript Free)
## License
MIT License © 2020 [Anthony Fu](https://github.com/antfu)
---
_Source: https://npm.io/package/rollup-plugin-purge-icons · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._