• What is svg-to-ts?
• Who is this for?
• Why you should use svg-to-ts
• Step by step guide on how to create your icon library
  • Video tutorials
  • Written tutorial
• How to use svg-to-ts
  • Usage
    • Binaries
    • Configuration
    • Passing arguments to the binary
    • Configure svg-to-ts over package.json
    • Configuration file
      • Using a custom path
  • ConversionTypes
    • 1. Converting to a single object (conversionType==='object')
      • Available options:
      • Example usage
      • Sample output
    • 2. Multiple constants - Treeshakable and typesafe with one file (conversionType==='constants')
      • Available options:
      • Example usage
      • Sample ouput
    • 3. Tree shakable and optimized for lazy loading (conversionType==='files')
      • Available options:
      • Example usage
      • Sample output
• SVGO - SVG optimization
• Starter project
• Angular builder
• FAQ
  • Which approach should I use
  • Is it possilbe to create a standalone library?
  • Can I use the icons to generate a type?
• Contributors ✨

What is svg-to-ts?

svg-to-ts is a helper tool that converts your SVG icons to TypeScript or TSX. svg-to-ts can convert SVGs to either one TypeScript / TSX file with exported constants, multiple TypeScript files or even compiled JavaScript files with according TS declaration files. Furthermore, it generates all typings in form of interfaces and types.

The generated output can then be used in combination with a iconregistry to create a tree shakable icon library. (More informations...)

Who is this for?

svg-to-ts is designed for autors of component libraries, icon libraries and SPA authors. Our examples and tutorials are made with Angular, however svg-to-ts can also be used with other frameworks such as React or vanilla TypeScript / JavaScript.

Why you should use svg-to-ts

• svg-to-ts helps you provide icons in a tree shakable and performant way.
• You get free step to step guides in form of blog posts, that walk you through the process of creating your own tree shakable icon library
• svg-to-ts optimizes your SVG icons under the hood
• svg-to-ts automatically generates types and interfaces for your icons to improve typesafety
• svg-to-ts was developed based on the experiences of providin an icon library for a large enterprise.
• svg-to-ts offers the possibility to generate TSX files (react components).
• offers three different conversion modes ('object', 'constants' and 'files')
• each method is highly configurable to supports multiple use cases.

Step by step guide on how to create your icon library

We created multiple tutorials to show you how you can use svg-to-ts in the best way. We have two step by step guides. A video course and a blog post. Both cover the same content. Feel free to choose the format you prefer.

Video tutorials

Written tutorial

This blog post guides you through the process of building your own icon library with svg-to-ts.

How to use svg-to-ts

svg-to-ts is a command line tool, it can either be used directly in your terminal or via npm script.

Usage

Binaries

svg-to-ts provides three different binaries.

• svg-to-ts-object
• svg-to-ts-constants
• svg-to-ts-files

You can either run those binaries with npx

npx -p svg-to-ts svg-to-ts-object

or you can add a new script in your package.json.

"name": "my-icon-library",
"version": "3.4.0",
"scripts": {
  "generate-icons": "svg-to-ts"
}

Configuration

When executing a binary svg-to-ts automatically applies some defaults. However, you have multiple ways to configure svg-to-ts. To get a list of available options you can either execute the binary of your choice with the --help argument or you can find all the available options for your conversion type here in the docs:

• 1. Converting to a single object (conversionType==='object')
• 2. Multiple constants - Treeshakable and typesafe with one file (conversionType==='constants')
• 3. Tree shakable and optimized for lazy loading (conversionType==='files')

Once you found your configurations you have the following possibilities to configure svg-to-ts:

• Passing arguments to the binary
• Adding a configuration object in the package.json
• Adding a .svg-to-tsrc file (javascript, json , yaml or yml) in the root of your project or a path of you choice.

Passing arguments to the binary

When choosing this option you directly pass the arguments to your binary.

svg-to-ts-files -s './inputfiles/*.svg' --compileSources true --additionalModelOutputPath ./additional

A complete list of the available arguments can be found by using the --help argument.

svg-to-ts-files --help

When you start using svg-to-ts in bigger projects, configuration may get more sophisticated. At this point command line arguments are hard to read.

Configure svg-to-ts over package.json

To configure svg-to-ts over package.json you can add a svg-to-ts key in your package.json and use the config options. Once you run svg-to-ts those configurations will be picked up. The config object can eiter be an object or an array containing multiple configurations.

{
  "name": "my-icon-library",
  "version": "3.4.0",
  "scripts": {
    "generate-icons": "svg-to-ts"
  },
  "svg-to-ts": {
    "srcFiles": ["./projects/dinosaur-icons/icons/**/*.svg"],
    "outputDirectory": "./projects/dinosaur-icons/icons",
    "interfaceName": "DinosaurIcon",
    "typeName": "dinosaurIcon",
    "prefix": "dinosaurIcon",
    "svgoConfig": {
      "plugins": ["cleanupAttrs"]
    },
    "fileName": "dinosaur-icon.model",
    "additionalModelOutputPath": "./projects/dinosaur-icons/src/lib",
    "compileSources": true
  }
}

Configuration file

To configure svg-to-ts over a .rc file you can add a .svg-to-tsrc file in the root of your project and use the config options. Once you run svg-to-ts those configurations will be picked up.

{
  "srcFiles": ["./projects/dinosaur-icons/icons/**/*.svg"],
  "outputDirectory": "./projects/dinosaur-icons/icons",
  "interfaceName": "DinosaurIcon",
  "typeName": "dinosaurIcon",
  "prefix": "dinosaurIcon",
  "fileName": "dinosaur-icon.model",
  "svgoConfig": {
    "plugins": ["cleanupAttrs"]
  },
  "additionalModelOutputPath": "./projects/dinosaur-icons/src/lib",
  "compileSources": true
}

An alternative for bigger projects is to use a JavaScript-based configuration file. The main advantage here is there you can create dynamic configurations, but also use plain-old JavaScript objects, allowing you to add comments, etc. This is useful for more complex configurations where comments can clarify why options are defined in a certain way.

JS configurations must be defined as a CommonJS module. Whenever you want to use a JS configuration file your rc file has to end with .js.

Here's an example:

const svgToTsConfig = {
  srcFiles: ['./libs/web-icons/icons/**/*.svg'],
  outputDirectory: './libs/web-icons/src/lib',
  interfaceName: 'MyIcon',
  typeName: 'MyIconName',
  generateType: true,
  modelFileName: 'whatever-icon.model',
  additionalModelOutputPath: './libs/web-icons/src/lib',
  iconsFolderName: 'generated',
  delimiter: 'SNAKE',
  barrelFileName: 'generated-icons-barrel',
  svgoConfig: {
    plugins: ['cleanupAttrs']
  },
  compileSources: false
};

module.exports = svgToTsConfig;

Using a custom path

In case you want to put your configuration under a custom path, you can use the --config property to specify a path your configuration. For example svg-to-ts --config ./myconfig.json.

ConversionTypes

svg-to-ts offers three different kinds of conversion types; Converting your icons to a single object, converting your icons to constants or converting your icons to single files. Each approach is designed to solve a specific kind of problem. You can switch between approaches by passing conversionType property (object, constants or files).

1. Converting to a single object (conversionType==='object')

In this scenario the SVG icons are converted to a single object. It's an approach that is suitable if your icon registry accepts an object with the filename as key and the svg data as key.

Available options:

Example usage

Let's say we have the following four svg files in a inputfiles folder.

• expressionless.svg
• full.svg
• laughing.svg
• smiling-face.svg

We can now run svg-to-ts-object -s ./inputfiles -o ./dist and we end up with the following file in our dist folder.

Sample output

export default {
  expressionLess: '<svg value="" method="" order="" version="" loading="" by="" pattern="" path="" display="" for="" is="" name="" default="" end="" step="" multiple="" type="" in="" xmlns="https://ww...',
  full: '<svg xmlns=">;

// resulting type is equal to type = 'smile' | 'laugh';

myMethod(): emojiIcons {
  // do stuff here
}

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Kevin Kreuzer 💻 🎨 📖 🤔 🚇 🚧 ⚠️	Shahar Kazaz 💻 📖 🤔 🚧 ⚠️	Felipe Plets 💻 📖 🤔 🚧 ⚠️	Raphael Ochsenbein 💻 📖 🤔 🚧 ⚠️	Guillaume M 💻 📖 🤔 🚧 ⚠️	Jaime Velay Valor 💻	Glenn Greibesland 💻
MrP 📖	Sebastien Dubois 📖	Andrew Polhill 💻 🐛 📖 🤔	Joshua Vinters 📖	Matthäus G. Chajdas 📖	Julian Kimmig 💻	Fernando Montoya 📖
Alexey Evenkov 💻	nmastereal 💻	Katya Pavlenko 💻 📖 🤔	Liran Tal 📖	Ikko Ashimine 📖	Theo Tonge 💻 📖 ⚠️	Kasper Christensen 📖
Antonio 📖	weihsma 💻 📖	Tomas Trajan 💻	Cory Lewis 📖	Logan Cool 🐛	Justin Dietz 🐛 💻 🤔 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!