Nukem's Possible Manifestation

    svg-chunk-webpack-plugin
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    SvgChunkWebpackPlugin

    GitHub Workflow Status (branch) Coverage Status Node.js

    Generate SVG sprites according to entrypoint dependencies. Each page only imports its own svgs, wrapped as a sprite and optimized by svgo.

    The SvgChunkWebpackPlugin creates optimized SVG sprites, according to Webpack's entrypoints. Each sprite contains only the SVG dependencies listed on its entrypoints to improved code splitting, even on SVG files.

    The plugin includes the popular svgo package to generates clean and optimized SVG sprites.

    Code splitting is the key to deliver files without any content that is unused by the pages. It already exists for CSS, Javascript and now for SVG files with this plugin.

    When to use this plugin

    On multiple page application, each pages must includes only its necessary dependencies. In other words, it must include only the SVG files imported by its entrypoint and all its dependencies.

    With reusable components, SVGs are often duplicated on all the project. Now, you can create a global SVG library and every Javascript files can easily import any SVG from this library. Entrypoint dependencies are automatically updated, thanks to the Webpack compilation.

    When you work with SVGs exported by design softwares, like Sketch or Illustrator, their source code is never optimized and often contains comments, CSS classes which can create conflicts between them. The plugin automatically cleans all SVGs before creating the sprite.

    Zero config

    The plugin works without configuration with already the optimized settings. For advanced usage, see the section using configuration.

    Installation

    The plugin is available as a package with the name of svg-chunk-webpack-plugin on npm and Github.

    npm install svg-chunk-webpack-plugin --save-dev
    yarn add svg-chunk-webpack-plugin --dev

    Environment

    SvgChunkWebpackPlugin was built for Node.js >=10.13.0 and Webpack >=5.10.3.

    Example

    The project includes a minimalist example in the ./example directory. Run the npm run build:example command to execute the Webpack example and see SvgChunkWebpackPlugin's implementation in action.

    Basic usage

    The plugin will generate one SVG sprite for each entrypoints. Sprites are built in the output path directory with all the other assets. Each sprite filename is composed with its entrypoint name (in the example below, that would be home.svg).

    First, let's add the loader and the plugin to the Webpack configuration.

    The loader and the plugin need to works together.

    webpack.config.js

    var SvgChunkWebpackPlugin = require('svg-chunk-webpack-plugin');
    var path = require('path');
    
    module.exports = {
      entry: {
        home: 'home.js'
      },
      output: {
        filename: 'bundle.js',
        path: path.resolve(__dirname, './dist')
      },
      module: {
        rules: [
          {
            test: /\.svg$/,
            use: [
              {
                loader: SvgChunkWebpackPlugin.loader
              }
            ]
          }
        ]
      },
      plugins: [new SvgChunkWebpackPlugin()]
    };

    💡 For more flexibility and better performance, inline SVG files are better. Fewer HTTP requests, CSS properties to change the style, no flickering during the page load.

    Then, include the sprite in the wanted pages (we use Twig in the following example).

    home.html.twig

    {{ include 'home.svg' }}

    Finally, use the SVG with the <use> tag, like the following example. Replace <SVG_FILENAME> by the SVG filename, without the extension.

    home.html.twig

    <svg>
      <use xlink:href="#<SVG_FILENAME>"></use>
    </svg>

    Using a configuration

    You can pass configuration options to SvgChunkWebpackPlugin to overrides default settings. The transmitted parameters will be merged with the default parameters listed above. Allowed values are as follows:

    filename

    String = '[name].svg'

    Tells the plugin whether to personalize the default sprite filename. The placeholder [name] is automatically replaced by entrypoints names.

    new SvgChunkWebpackPlugin({
      filename: '[name].svg';
    });

    The filename parameter is compatible with Webpack caching placeholders, see the section caching.

    svgoConfig

    Object = {}

    Tells the plugin whether to personalize the svgo configuration.

    new SvgChunkWebpackPlugin({
      svgoConfig: {
        multipass: true, // Recommended
        plugins: [
          {
            name: 'preset-default',
            params: {
              overrides: {
                inlineStyles: {
                  onlyMatchedOnce: false
                },
                removeViewBox: false
              }
            }
          },
          {
            name: 'convertStyleToAttrs' // Disabled by default since v2.1.0
          }
        ]
      }
    });

    svgstoreConfig

    Object = { cleanDefs: false, cleanSymbols: false, inline: true }

    SVG sprites are built using the svgstore package. Update the parameters according to your needs from the options list available on the svgstore documentation.

    💡 To avoid LinearGradient conflicts, avoid the display: none property which breaks SVG definitions.

    new SvgChunkWebpackPlugin({
      svgstoreConfig: {
        svgAttrs: {
          'aria-hidden': true,
          style: 'position: absolute; width: 0; height: 0; overflow: hidden;'
        }
      }
    });

    generateSpritesManifest

    Boolean = false

    Tells the plugin whether to generate the sprites-manifest.json. The JSON file contains the list of all SVG included by entrypoints. It becomes very easy to known which SVG are included in which sprite.

    new SvgChunkWebpackPlugin({
      generateSpritesManifest: true
    });

    generateSpritesPreview

    Boolean = false

    Tells the plugin whether to generate the sprites-preview.html. The HTML preview contains a display list of all SVG included by entrypoints with the SVG overviews and the names.

    new SvgChunkWebpackPlugin({
      generateSpritesManifest: true
    });

    Sprites preview


    Caching

    With Webpack caching, several placeholders are available depending on your needs. With SVG inlined in the page, this option is not useful.

    💡 The [contenthash] placeholder is the best option because it depends on the sprite content.

    Cache placeholders are expensive in build performance, use it only in production mode.

    [hash]

    The [hash] placeholder will add a unique hash generated for every build. When the compilation build is updated, [hash] will change as well. See the stats.hash on the webpack documentation.

    new SvgChunkWebpackPlugin({
      filename: '[name].[hash].svg';
    });

    [chunkhash]

    The [chunkhash] placeholder will add a unique hash based on the content of the entrypoint. When the entrypoint's content changes, [chunkhash] will change as well. All the entrypoint dependencies will have the same hash.

    new SvgChunkWebpackPlugin({
      filename: '[name].[chunkhash].svg';
    });

    [contenthash]

    The [contenthash] placeholder will add a unique hash based on the content of the sprite. When the sprite's content changes, [contenthash] will change as well.

    new SvgChunkWebpackPlugin({
      filename: '[name].[contenthash].svg';
    });

    Licence

    SvgChunkWebpackPlugin is licensed under the MIT License.

    Created with by @yoriiis.

    Install

    npm i svg-chunk-webpack-plugin

    DownloadsWeekly Downloads

    57

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    41 kB

    Total Files

    15

    Last publish

    Collaborators

    • yoriiis