@geocompy/icosystem-cli

Icosystem CLI

Icosystem CLI is a utility that creates SVG <symbol>'s by simply stating what icons you want to use.

v0.3.0 - Breaking changes

Configuration Requirements

Icon config files now require family and icons props, which means simple icon arrays are not valid anymore:

// not valid
module.exports = ['magnify', 'help']

// valid
module.exports = {
  family: 'material',
  icons: ['magnify', 'help']
}

Removal of CLI options

Writing out multiple options every time you needed to add an icon is redundant - and since we're already writing a config for our icons list, it just makes sense to require family as well, and remove most of the CLI options.

CLI options being removed:

• --icon-family (now family prop in config)
• --file-type (only supporting js files for now)
• --export-type (only supporting es6 modules for now)

Output file rename

Changed the output file's name from svg-symbols.js to icon-symbols.js.

Technical Things

I did a complete overhaul of the build process (even reduced the code footprint a bit 😄):

• Code is clearly formed in a pipeline
• Self documented with some JSDocs
• cleaned up some global messiness
• Added more (clearer) error messages

---

Icons

This repo depends on open source SVG icon sets. Icons available:

• Material Design Icons (family = material)
• weather-icons (family = weather)
• More coming soon.

You can also use local icon sets - see Custom Icon Sets to learn more.

Install

npm install -g @geocompy/icosystem-cli

Configuration

The CLI requires a config file that tells it how to retrieve icons and how to process them. The minimum requirements to writing a config are the props family and icons.

module.exports = {
  family: 'material',
  icons: ['account', 'magnify']
};

Use

Run the CLI and target your file:

$ ico path/to/config-file.js

The CLI generates a new file called icon-symbols.js that contains your specified icon sets:

import { icons } from './icon-symbols.js'
let rootTemplate = `<div>${icons}</div>`

Options

Multiple Icon Sets

You can add multiple icon sets by creating a collection of configs:

// collection of configs
module.exports = [
    {
      family: 'weather',
      icons: ['cloudy'],
      prepend: 'wi'
    },
    {
      family: 'material',
      icons: ['account', 'magnify'],
      prepend: 'mdi'
    }
];

To avoid name collisions between icon sets, the prepend prop is required, which will prepend all icon names id's and mappings. See Prepend icon names to learn more.

Select all icons in a set

Select all icons in a set by putting a single * in your icon array:

// single config
module.exports = {
  family: 'weather',
  icons: ['*']
};

Custom icon sets

Sometimes, you'll need to add an icon set that's not open source (or just not available yet in the CLI). You can add it by adding a directory prop to your config:

module.exports = {
  family: 'font-awesome-pro',
  directory: 'path/to/icons',
  icons: ['bars']
}

Directory Caveat: The CLI assumes this directory is a folder containing ALL of your SVG's for the icon set. It does not dig through sub-folders (but maybe it should?).

Icon Map

The CLI generates a map of every icon being passed in. This could be helpful to programatically check if icons are available, generating lists, etc. Each icon in the map has a viewBox property in case you need it (helpful when using a variable-width icon set).

This option is true by default, but you can turn it off as well:

module.exports = {
  family: 'weather',
  icons: ['*'],
  map: false
}

The map is accessible in the same icon-symbols.js file, under iconMap:

import { iconMap } from './icon-symbols';

Prepend icon names

Prepend icon names with another name:

module.exports = {
  family: 'font-awesome-pro',
  prepend: 'fa',
  directory: 'relative/path/to/icons',
  icons: ['bars']
}

// the "bar" icon will look like:
// id="fa-bars"

NOTES

• When adding multiple icon sets to your config, the prepend prop is required to avoid name collisions.
• The weather icon set SVG's comes with a prepended name wi-. We actually remove this to allow for customizability with prepended names.

CLI Arguments

Required Argument: <File> (Icon config)

Path to your config file.

Options

Flag	Short Flag	Description
--output	-O	Set output path

Weather Icon Note

If you go to the weather-icons site you'll notice that each icon is prepended with wi-. This prepended name is not required when adding icons (in fact, if you add wi- on the name, it won't be able to find the icon):

module.exports = {
  family: 'weather',
  icons: ['cloudy'] // we'll grab wi-cloudy
}

Roadmap

• Add a config so you can change the defaults v0.2.0
• Add more open source icon families (Streamline free, Feather, etc) Might even add attribution icons as well - The Noun Project is full of them...
• Add some tests.

Input is appreciated! I'm open to ideas and would love to collaborate to make this an awesome project.