purgesvg
v1.1.0
Published
Remove unused svg symbols and optionaly merge svg files
Downloads
3,825
Readme
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.
:bangbang: Warning :bangbang:️
Be aware that external SVG sprites are not supported in any version of IE. If you need support for IE check out svg4everybody.
:heart: Gratitude :heart:
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
:heavy_check_mark: 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
:wrench: TODO :hammer:
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'])
}
}