PurgeSvg

What is PurgeSvg

If you're using external SVG sprites for your icon system there is a good chance you have a lot of unused icons at the end.

PurgeSvg will analyze your content and remove all unused icons. This will make your SVG file a lot smaller.

It also enables you to merge more SVG files into one and thereby reducing network requests.

‼️ Warning ‼️️

Be aware that external SVG sprites are not supported in any version of IE. If you need support for IE check out svg4everybody.

❤️ Gratitude ❤️

This package was inspired (and some code copied) from Purgecss

Usage

CLI

Start by installing the package globally

npm i -g purgesvg

PurgeSvg is available via a CLI. You can use the CLI by itself or with a configuration file.

To see the available options for the CLI: purgesvg --help

purgesvg --content <content> --svgs <svgs> [option]

Options:
  -c, --config     configuration file                                   [string]
  -o, --out        Filepath directory to write purified svg files to    [string]
  -w, --whitelist  List of id's that should not be removed [array] [default: []]
  -h, --help       Show help                                           [boolean]
  -v, --version    Show version number                                 [boolean]

Using configuration file

purgesvg --config /path/to/config.js

Options

✔️ When not using a configuration file the --content and --svgs options are required.

• --content

Content that should be analyzed. An array of filenames or glob.

purgesvg --content index.html /resource/assets/**/*.vue --svgs ...

• --svgs

SVG files to purge. An array of filenames or glob.

purgesvg --content index.html --svgs /images/icons.svg /icons/solid.svg

• --out

Output path for purged SVGs.

The output path can be:

• a directory - the purged files will be placed in this folder with the same filename as the SVG
• a path to a file - all SVGs will be purged and merged into this file
• missing - if this option is missing the purged SVGs will be put beside the original file as filename.purged.svg

purgesvg --content index.html --svgs /icons/*.svg --out /build/purged/icons.svg

• --whitelist

List of whitelist ids. Id's will be whitelisted for all SVG files.

purgesvg --content index.html --svgs /icons/*.svg --whitelist rocket heart times

JavaScript

Start by installing the package as a development dependency

npm i --save-dev purgesvg

You can use PurgeSvg in your javascript file. Just require the package, create the new PurgeSvg class, add configuration options and call the purge method.

The constructor accepts a configuration object or a path to the configuration file.

const PurgeSvg = require('purgesvg')

new PurgeSvg({
    content: './__tests__/test_examples/clean_svgs/index.html',
    svgs: [{
        in: './__tests__/test_examples/clean_svgs/icons.svg',
        out: tempFolder
    }],
    whitelist: {'*': ['building']}
}).purge()

WebPack

🔧 TODO 🔨

Configuration

Options

• content

Content that should be analyzed. The content option is an array of files or globs.

new PurgeSvg({
    content: ['index.html', `**/*.js`, '**/*.html', '**/*.vue'],
    ...
}

• SVGs

A list of SVG files that should be purged and their output configuration. The list could be an array of files/globs or an array of objects.

When provided as an array of strings (files/globs) the purged file will be saved in the same folder as the original as filename.purged.svg.

new PurgeSvg({
    svgs: ['images/icons.svg'], // purged file will be saved in 'images/icons.purged.svg'
    ...
}

Providing an array of objects enables more versatility. Some examples of different options:

new PurgeSvg({
    svgs: [
        // purged file will be saved in 'build/images/icons.svg'
        {
            in: 'images/icons.svg', // full path
            out: 'build/images' // only folder
        },
        
        // purged AND MERGED files will be saved in 'build/images/merged.svg'
        {
            in: 'icons/*.svg', // glob
            out: 'build/images/merged.svg' // full path
        }
    ],
    ...
}

• whitelist

Provides the option to whitelist ids of SVG sprites. The option can be used to whitelist ids for all files or only for specific SVG files.

new PurgeSvg({
    whitelist: {
        '*': new Set(['rocket', 'heart', ...]), // whitelist id's for all files
        'solid.svg': new Set(['building', 'times', ...]) // whitelist id's only for a specific file
    },
    ...
}

Configuration file

The configuration file is a simple JavaScript file containing options:

module.exports = {
    content: ['index.html'],
    svgs: [{
        in: 'images/*.svg'
    }],
    whitelist: {
        '*': new Set(['rocket', 'building'])
    }
}