todaytix/svg-sprite-webpack-plugin

Webpack plugin for loading/extracting SVGs into a sprite file

SVG Sprite Webpack Plugin

Description

A webpack plugin/loader to make SVG <use>-based icon systems easy in Webpack. Creates an SVG sprite with <symbol> tags from imported SVG files, and returns a URL to be passed to an SVG <use> tag. Uses kisenka's svg-sprite-loader for internal transformations (from standalone SVG file to <symbol> tag).

Installation

npm install --save-dev svg-sprite-webpack-plugin

Usage

Webpack config

const IconPlugin = require('svg-sprite-webpack-plugin').plugin;

// NOTE:
// Usage with the included webpack-isomorphic-tools parser requires that
// the extracted filename match this format.
const iconPlugin = new IconPlugin('icons-[hash].svg');

// ... inside the configuration object
{
  module: {
    loaders: [
      {
        test: /\.svg$/,
        loader: iconPlugin.extract(),
      }
    ]
  },
  plugins: [
    iconPlugin,
  ],
}

Webpack isomorphic tools

If using webpack-isomorphic-tools, add this to your config:

const iconParser = require('svg-sprite-webpack-plugin').webpackIsomorphicParser;

{
  assets: {
    svg: {
      extension: 'svg',
      parser: iconParser,
    }
  }
}

In code

An example using React 0.14 or later:

import { Component } from 'react';
import myGreatIcon from './my-great-icon.svg';

class SuperGreatIconComponent extends Component {
  render() {
    return (
      <svg><use xlinkHref={myGreatIcon} /></svg>
    );
  }
}

Suggested development mode config

If you're using the webpack-dev-server, it's advised to not use this plugin, and instead go directly to svg-sprite-loader.

const iconTest = /\.svg$/;
if (DEV) {
  config.module.loaders.push({
    test: iconTest,
    loader: 'svg-sprite',
  });
} else {
  config.module.loaders.push({
    test: iconTest,
    loader: iconPlugin.extract(),
  });
}

Usage Caveats

Internet Explorer

Internet Explorer does not support <use> tags with external references. This has been fixed in Microsoft Edge 13, but until Edge's browser share gets to an acceptable level for you, I suggest using jonathantneal's excellent SVG4Everybody library.

CDNs

<use> tags do not allow cross-origin requests, and from what I could tell, aren't likely to start supporting them any time soon. Because of this, instead of using the output.publicPath webpack config, this library is currently expecting that the generated icons svg will be accessible inside the /static directory on the same domain as the website using the imported icons.

Development

This was originally developed to be used in-house, so I expect there are a number of usecases that are not being adequately covered. Issues and PRs are welcome!

Install dependencies:

npm install --global yarn
yarn install

Make sure any code passes tests and the linter before submitting a PR!

yarn test
yarn run lint

Meta

Distributed under the MIT License. See LICENSE for more information.

Developers:

Jeremy Tice @jetpacmonkey

svg-sprite-webpack-plugin's Issues

Make icon file's public path configurable

Right now, the generated icon file is expected to be found inside the /static directory. My original rationale for using that instead of the publicPath in the webpack config was because <use> tags don't support cross-origin requests, and publicPath is often used to set to a CDN's domain. A better, more widely usable solution would be to take a config option in the plugin's constructor, have publicPath as a setting, and fallback to the webpack default publicPath if one is not specified.

Nested <defs> don't seem to work

This one needs more research. It appears an icon's internal <defs> aren't getting pulled out properly, or are at least causing something to break. In our usage, this hasn't been a huge issue, since I can just inline any of those defs into the icon itself, but it's definitely an annoying step in between a simple export from Sketch/Inkscape/Illustrator and using the icon.

Webpack 2 Support

Based on reading the migration guide, it looks like all of the config options should still work, although module.loaders is referred to as a "legacy option". ExtractTextPlugin, which has some similar functionality to this one, changed its API for v2, although I haven't found an explanation of how the internals changed yet, so we should at least consider doing the same.

Take a regex to identify the icon file in webpackIsomorphicParser

Currently, webpackIsomorphicParser has a hard-coded const iconsFileRE = /icons-[a-f0-9]+\.svg/i;. Ideally, there'd be some way for the parser to access the plugin from the webpack config, and get the filename from there. A slightly lesser solution would be to simple take in the same pattern that the plugin does, and let the user deal with keeping that in sync.