🧩 vite-plugin-shopify-icons-liquid

A lightweight Vite plugin that automatically builds a Shopify Liquid snippet containing your SVG icons fully optimized, accessible, and ready to use with {% render 'icon' %}.

🚀 Features

• ⚡ Automatic snippet generation (icon.liquid)
• 🌟 Automatic preview generation (icon-preview.html)
• 🔁 Incremental rebuilds (only updates changed icons)
• 🎨 SVG optimization with SVGO
• 📁 Supports nested folders (optional)
• 💬 Accessible attributes (aria-label, role, fill, etc.)
• 🧠 Smart caching & debounce for fast rebuilds
• 🧾 Optional JSON export with all icon names
• 🖍️ Colorful logs for better developer experience

📦 Installation

npm install vite-plugin-shopify-icons --save-dev

or

yarn add -D vite-plugin-shopify-icons

⚙️ Usage

Add the plugin to your vite.config.js:

// vite.config.js
import VitePluginShopifyIcons from 'vite-plugin-shopify-icons-liquid';

export default {
  plugins: [
    VitePluginShopifyIcons({
      inputDirectory: './frontend/icons',    // Folder with SVGs
      outputFile: './snippets/icon.liquid',  // Snippet to generate
      outputFileJSON: 'icons.json',          // Optional: also generate icons.json
      previewFile: 'icon-preview.html',      // HTML to preview your icons
      preview: true,                         // Enable preview mode
      openPreview: false,                    // Open preview file automatically
      flattenFolders: true,                  // Include subfolders in icon names
      verbose: true,                         // Show logs
      svgoConfig: {
        multipass: true,
        plugins: [
          'removeDimensions',
          { name: 'removeAttrs', params: { attrs: '(data-name)' } }
        ]
      }
    })
  ]
};

🧱 Example

Assume you have the following structure:

frontend/
  icons/
    cart.svg
    social/
      facebook.svg
      twitter.svg

When you run Vite, the plugin generates:

snippets/
  icon.liquid
icon.json (if enabled)

💎 Example snippet usage in Shopify

Once built, you can use your icons anywhere in your Shopify theme:

{% render 'icon', name: 'icon-cart', class: 'icon--md', fill: '#000', label: 'Cart', role: 'img' %}
{% render 'icon', name: 'icon-social-facebook', fill: 'blue', width: '20', height: '20' %}

🧩 Output (auto-generated icon.liquid)

The plugin generates a single snippet containing all icons:

{% comment %} Auto-generated by vite-plugin-shopify-icons {% endcomment %}
{% assign icon_class = "icon icon-" | append: name | replace: 'icon-icon-', 'icon-' %}
{% assign icon_fill = fill | default: "currentColor" %}
{% assign icon_label = label | default: name %}
{% assign icon_role = role | default: "" %}
{% case name %}
  {% when "icon-cart" %}
  <div class="{{ icon_class }}">
    <svg fill="{{ icon_fill }}" aria-label="{{ icon_label }}" role="{{ icon_role }}">
      <!-- Optimized SVG content -->
    </svg>
  </div>
{% endcase %}

🧠 Options

| Option | Type | Default | Description | | ---------------- | --------- | ------------------------------------- | -------------------------------------------------------------------------------------- | | inputDirectory | string | './assets' | Directory containing SVG icons | | outputFile | string | './snippets/icon.liquid' | Output Liquid snippet path | | outputFileJSON | boolean | false | Generate a JSON file with available icons | | flattenFolders | boolean | true | Include subfolders and flatten paths (e.g. social/facebook → icon-social-facebook) | | verbose | boolean | true | Print detailed build logs | | svgoConfig | object | { multipass: true, plugins: [...] } | Custom SVGO configuration |

🧾 JSON Output Example

When outputFileJSON: true, the plugin also generates:

{
  "icons": [
    "icon-cart",
    "icon-social-facebook",
    "icon-social-twitter"
  ]
}

Useful for autocomplete, documentation, or validation in CI/CD.

🔧 Dev mode (watcher)

When running vite dev, the plugin watches the SVG directory and automatically regenerates the snippet when SVGs are added, changed, or removed.

It uses a debounce mechanism (250 ms) to prevent unnecessary rebuilds.

🌟 Preview mode

When running vite dev, the plugin creates a preview fille automatically.

🧱 Build mode

During vite build, the plugin automatically generates the snippet once at the beginning of the process.

🧩 Recommended folder structure

my-shopify-theme/
├── frotend/
│   └── icons/
│       ├── cart.svg
│       └── social/
│           ├── facebook.svg
│           └── twitter.svg
├── snippets/
│   └── icon.liquid
├── vite.config.js
└── package.json

🧠 Tips & best practices

• Keep icons monochromatic and rely on fill for color control.
• Use lowercase file names and kebab-case (e.g. add-to-cart.svg → icon-add-to-cart).
• Combine with a linter or SVGO CLI to pre-clean icons from Figma/Sketch.
• Use aria-label for accessibility when icons are interactive.

💬 Changelog

**1.1.0

• Preview mode available

1.0.0

• Initial release 🎉
• Supports automatic snippet generation and live rebuilds.
• Added cache, debounce, and folder flattening.
• Optional icons.json output.

📄 License

ISC

Built for developers who love automating Shopify theme workflows. If you find this plugin useful, consider giving it a ⭐ on GitHub!