{"id":17150950,"url":"https://github.com/drolsen/webpack-svg-spritely","last_synced_at":"2025-04-13T11:52:54.770Z","repository":{"id":35068689,"uuid":"202911517","full_name":"drolsen/webpack-svg-spritely","owner":"drolsen","description":"Webpack plugin that bundles SVG files into a SVG sprite.","archived":false,"fork":false,"pushed_at":"2025-02-21T09:25:08.000Z","size":871,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T03:04:35.576Z","etag":null,"topics":["sprite","svg","svg-sprite","webpack","webpack-plugin","webpack-svg"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drolsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-17T17:21:07.000Z","updated_at":"2025-03-13T08:54:59.000Z","dependencies_parsed_at":"2024-10-23T00:59:09.272Z","dependency_job_id":null,"html_url":"https://github.com/drolsen/webpack-svg-spritely","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drolsen%2Fwebpack-svg-spritely","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drolsen%2Fwebpack-svg-spritely/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drolsen%2Fwebpack-svg-spritely/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drolsen%2Fwebpack-svg-spritely/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drolsen","download_url":"https://codeload.github.com/drolsen/webpack-svg-spritely/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248710439,"owners_count":21149188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["sprite","svg","svg-sprite","webpack","webpack-plugin","webpack-svg"],"created_at":"2024-10-14T21:36:54.501Z","updated_at":"2025-04-13T11:52:54.748Z","avatar_url":"https://github.com/drolsen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"/assets/logo.png\" width=\"300\" /\u003e\n  \u003cp style=\"margin-top: 25px;\"\u003ePlugin that bundles project SVG files into a SVG sprite.\u003c/p\u003e\n\n[![Build Status](https://app.travis-ci.com/drolsen/webpack-svg-spritely.svg?branch=master)](https://app.travis-ci.com/drolsen/webpack-svg-spritely)\n[![Minimum node.js version](https://badgen.net/badge/node/%3E=14.17.0/green)](https://npmjs.com/package/webpack-svg-spritely)\n[![downloads](https://img.shields.io/npm/dm/webpack-svg-spritely.svg?style=flat-square)](http://npm-stat.com/charts.html?package=webpack-svg-spritely\u0026from=2022-01-08)\n[![version](https://img.shields.io/npm/v/webpack-svg-spritely.svg?style=flat-square)](http://npm.im/webpack-svg-spritely)\n[![GitLab release](https://badgen.net/github/releases/drolsen/webpack-svg-spritely)](https://github.com/drolsen/webpack-svg-spritely/releases)\n[![MIT License](https://img.shields.io/npm/l/webpack-svg-spritely.svg?style=flat-square)](http://opensource.org/licenses/MIT)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/drolsen/webpack-svg-spritely/graphs/commit-activity)\n\u003c/div\u003e\n\n### How it works\nWebpack SVG Spritely takes all incoming SVG files of a given build and creates symbols out of them.\nTaking the created symbols, Webpack SVG Spritely then writes an SVG sprite file to disk or document(s).\n\nOnce ran in browser, the newly created SVG sprite is loaded into DOM and ready for usage.\n\nIt's that simple!\n\n---\n### Install\n```\nnpm i --save-dev webpack-svg-spritely\n```\n```\nyarn add --dev webpack-svg-spritely\n```\n\n### Webpack Config\nImport `webpack-svg-spritely` into your Webpack configuration file:\n\n```js\nconst WebpackSVGSpritely = require('webpack-svg-spritely');\n```\n\nInstantiate new `WebpackSVGSpritely(...)` class within Webpack's plugin configuration array:\n```js\nmodule.exports = {\n  \"plugins\": [\n    new WebpackSVGSpritely()\n  ]\n};\n```\n\n---\n\n## Options\n\n```js\nmodule.exports = {\n  \"plugins\": [\n    new WebpackSVGSpritely({\n      ...options...\n    })\n  ]\n};\n```\n\nOption | Types | Description | Default\n--- | --- | --- | ---\n`output` | String | Location of where sprite file gets written to disk. | Relative to Webpack build's output.\n`filename` | String | Name of the sprite file that gets written to disk. | iconset-[hash].svg\n`filter` | String Array | Name of the SVG files you wish to exclude from sprite(s). | no filtering\n`prefix` | String | Prefix used in the sprite file symbol's name | `icon-`\n`insert` | String | Defines HOW svg sprite symbols get inserted into DOM (xhr, bundle, none). | xhr method\n`location` | String | Defines WHERE SVG sprite symbols DOM will be injected. | bodyStart\n`url` | String | Overloads the `insert.xhr` option's request URL. | Relative to root of server.\n`entry` | String Array | Allows you to define what entry file(s) or html document(s) to insert sprite or XHR JS into. | All webpack entry files\n`combine` | Boolean | Combines all SVG files into single sprite across multiple Webpack entry files. | false\n`manifest` | String or Object | Allows you to define path and filename to a generated a JSON manifest file of found symbols.\n\n## options.output\nWith the `output` option, you can specify a deeper location to where this plugin should write the sprite file under.\nWithout this option, the sprite file will be written to the root of your Webpack configuration's output location.\n\n```js\nnew WebpackSVGSpritely({\n  output: '/custom/location/images'\n})\n```\n\n## options.filename\nThis option allows you to specify a custom name for the sprite file.\nYou can use a `[hash]` flag to combine a MD5 cache pop hash to filenames.\n\n**Note:** if you using a [hash] flag within `filename` you are subjected to unique hash numbers per build. Consider removing `[hash]` flag, if you have logic beyond this plugin that needs a consistent sprite filename when written to disk.\n\n```js\nnew WebpackSVGSpritely({\n  filename: 'custom-svg-sprite-[hash].svg'\n})\n```\n\n## options.filter\nThis option allows you to specify an array of SVG filenames you wish to exclude from generated sprite sheets.\n\n**Note:** There is no RegEx or wildcard abilities here and must be an exact 1:1 of the SVG filename you wish to explicitly exclude. However the inclusion or exclusion of SVG file extension is optional to help curve any miss configurations.\n\n```js\nnew WebpackSVGSpritely({\n  filter: ['bob.svg', 'ross.svg', 'paintings']\n})\n```\n\n## options.prefix\nThe `prefix` option allows you to change a symbol's id prefix from `icon-` to something custom. \nFor example, if you have SVG files named `up.svg` and `down.svg`, by default both `up.svg` and `down.svg` sprited ids are `icon-up` and `icon-down` respectively.\n\n```js\nnew WebpackSVGSpritely({\n  prefix: 'projectName'\n})\n```\n\nwhich effect sprite usage:\n```xml\n\u003csvg\u003e\n  \u003cuse xlinkHref=\"#projectName-up\" /\u003e\n\u003c/svg\u003e\n\n\u003csvg\u003e\n  \u003cuse xlinkHref=\"#projectName-down\" /\u003e\n\u003c/svg\u003e\n```\n\n## options.insert\nThe insert option allows you to define how sprite symbols gets inserted into the DOM for sprite usage when ran in browsers.\n\n```js\nnew WebpackSVGSpritely({\n  insert: 'xhr | bundle | none'\n})\n```\n\n### xhr (default)\nXHR code snip get inserted into your build's entry file(s). The XHR option will fire off a request (at page load) to a sprite file that gets written to disk and loads symbols into DOM. This is to help to reduce your entry bundled size by offloading sprite source to a file on disk, but does not work offline.\n\n### bundle\nIf you wish to not write sprite to disk / XHR option, you can bundle sprite symbols directly into your build's entry file(s) instead. This can increase your bundled size pretty quickly, but does ensure svg sprite works offline.\n\n### none\nWhen working with larger backend systems (Java or .Net) that inserts sprite symbols into documents, use the none option.\nThis will still write a sprite file to disk for backend, but bypass any code from being inserted into client side documents.\n\n## options.location\nThe location options lets you define where in the DOM sprite svg source will live.\n\n```js\nnew WebpackSVGSpritely({\n  location: 'bodyStart | bodyEnd'\n})\n```\n\n### bodyStart\nThis option will insert the sprite sheet DOM into the start of the document body using insertBefore method.\n\n### bodyEnd\nThis option will insert the sprite sheet DOM into the end of the document body using append method. No guarantee it will be the last child in head.\n\n\n## options.url\nIf you choose to set the `insert.xhr` option, the default request location for sprite file will be `output location + filename`. If you wish to overload this default file endpoint you can do so with this option.\n\n```js\nnew WebpackSVGSpritely({\n  url: '/~/custom/production/path'\n})\n```\n\n## options.entry\nIf you would like to specify a specific file to insert code into (when using multiple entry files or html documents), this `entry` option will allow you to do just that. By default, without specifying an entry file, code can be inserted into all webpack configured entry files.\n\nIf you referencing a by imported file name or by shorthand name:\n```js\nmodule.exports = {\n  \"entry\": {\n    testA: 'test.a.js',\n    testB: 'test.b.js'\n  },\n  output: {\n    filename: '../dist/basic/[name].js'\n  },\n  \"plugins\": [\n    new WebpackSVGSpritely({\n      insert: 'xhr|bundle',\n      entry: ['testB']\n    })\n  ]\n};\n```\n\n```js\nmodule.exports = {\n  \"entry\": {\n    testA: 'test.a.js',\n    testB: 'test.b.js'\n  },\n  output: {\n    filename: '../dist/basic/[name].js'\n  },\n  \"plugins\": [\n    new WebpackSVGSpritely({\n      insert: 'xhr|bundle',\n      entry: ['test.b.js']\n    })\n  ]\n};\n```\n\nIf using html entry instead: \n```js\nmodule.exports = {\n  \"entry\": {\n    testA: 'test.a.js',\n    testB: 'test.b.js'\n  },\n  output: {\n    filename: '../dist/basic/custom-[name].js'\n  },\n  \"plugins\": [\n    // used to compile our html files\n    new HtmlWebPackPlugin({\n      'template': './src/index.html',\n      'filename': './documents/[name].html',\n    }),\n    new WebpackSVGSpritely({\n      insert: 'xhr|bundle',\n      entry: ['index.html']\n    })\n  ]\n};\n```\n\n## options.combine\nWhen using multiple entry files for a Webpack configuration: \n```js\nentry: {\n  testA: 'test.a.half.js',\n  testB: 'test.b.half.js'\n}\n```\n\nWebpack SVG Spritely will (by default) create unique sprite sheets per configured entry files. Each sprite sheet containting only it's corresponding entry file's SVG files.\n\nHowever, if you would like to consolidate all svg files from multiple entry files in a single sprite sheet setting the combine option to `true` will do just that: \n\n```js\nnew WebpackSVGSpritely({\n  combine: true\n})\n```\n\n**Note:** Because of the way HTML documents are brought into Webpack builds by means of HTMLWebpackPlugin:\n```js\nnew HtmlWebPackPlugin({\n  'template': './some.html',\n  'filename': './index.html',\n}),\n```\nThere is zero association to these configured HTML documents, and one or another entry file. Therefor, if you have configured Webpack SVG Spritely to use `insert: 'document'` this combine option will have no effect, and your HTML document(s) will contain assets from all configured entry files.\n\n## options.manifest\nThis option allows you to set both the path and filename of a JSON manifest file. \nThis manifest file contains the name and individual SVG source of all the captured icons into a JSON format.\n\n```js\nnew WebpackSVGSpritely({\n  manifest: '/path/filename.json'\n})\n```\n\nThis is useful for larger systems that wish to present a list of available icons to end users, that needs to be devoid of any JS, or even possibly \"in-browser\" requirements.\n\nBy default this is false, and only enabled once you provide a string path or object options. This will always generate a JSON format, so ensure that you choose .json as your path/filename's format.\n\nYou can also `groupBy` your icons within the manifest json:\n```js\nnew WebpackSVGSpritely({\n  manifest: {\n    path: '/path/filename.json',\n    groupBy: ['red', 'blue', 'green']\n  }\n})\n```\n\nThe `groupBy` feature will group all icons that have a matching name to your configured words. The manifest.json  groupings are objects that use keys names from your configuration. All icons that do not match any `groupBy` configuration will be put into the object named \"icons\".\n\nYou can also `filterOut` icons from the manifest json:\n```js\nnew WebpackSVGSpritely({\n  manifest: {\n    path: '/path/filename.json',\n    filterOut: ['red', 'blue', 'green'],\n  }\n})\n```\n\nThe `filterOut` feature will exclude all icons that have a matching name to your configured words.\n\nKeep in mind that with options configuration you need to supply the `path` as a explicit property.\n\n---\n\n### Using Sprite Parts\nTo reference SVG sprite parts in DOM, use the `xlinkHref` within a SVG tag:\n\n```xml\n\u003csvg\u003e\n  \u003cuse xlinkHref=\"#icon-[filename]\" /\u003e\n\u003c/svg\u003e\n```\n\n- `[filename]` would be substituted with the actual filename of source SVG you wish to render.\n- `icon-` prefix of the xlinkHref is default of Webpack SVG Spritely but can be customized with the `prefix` option below.\n\n### Plugin Requirements\nThe only requirement Webpack SVG Spritely has, is that you are passing SVG's through your build system, not just coping them from one location to another by means of [CopyWebpackPlugin](https://www.npmjs.com/package/copy-webpack-plugin).\n\nInclude all SVG files into your Webpack entry file(s):\n```js\nrequire.context('src/project/images/', false, /\\.(svg)$/);\n```\n\nIf you have not already configured your Webpack to handle media files, have a look see at the Webpack SVG Spritely test configuration [here](https://github.com/drolsen/webpack-svg-spritely/blob/master/test/basic.test.config.js#L16-L27) to see how to use `file-loader` module. This must be setup prior to importing your source SVG files into your bundle(s).\n\nFor any questions around Webpack image configuration, please first review [repository test files](https://github.com/drolsen/webpack-svg-spritely/tree/master/test) before opening an issue.\n\n---\n\n### Tests\n\nWebpack SVG Spritely comes with a number of tests found under `/tests`.\nThese are here to help you better understand the expectations of each option we covered above.\n\nSimply run `npm run test` or `yarn test` from the root of the plugin to run all tests. Running a test will produce a `/dist/[test]` directories. With each test, be sure to review the bottom of the bundled.js file(s), and the sprite file to understanding changes taking place from test to test.\n\nIf you would like to change a test, update the root package.json file's `test` script to use any of the `/test/*.test.config.js` files.\n\n`test.a.js` and `test.b.js` files are our test supporting entry files, not test configurations. Both these files are requiring our test svg files which is a requirement of Webpack SVG Spritely.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrolsen%2Fwebpack-svg-spritely","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrolsen%2Fwebpack-svg-spritely","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrolsen%2Fwebpack-svg-spritely/lists"}