# Configuration / ungic.config.json

On this page, you can get information about the ungic.config.json project configuration file.

This file is created during initialization or when creating a new ungic project.

TIP

Some of the main parameters of this config. file are similar to the parameters of package.json, so we recommend installing ungic after initialization npm: npm init ungic init

# An example of a config file:

{
  "name": "appName",
  "version": "1.0.0",
  "mode": "development",
  "author": "unbywyd",
  "server": {
    "port": 2020
  },
  "openInBrowser": true,
  "fs": {
    "dirs": {
      "source": "source",
      "dist": "dist",
      "temp": "temp"
    },
    "dist": {
      "css": "css",
      "fonts": "fonts",
      "img": "img",
      "js": "js"
    },
    "source": {
      "scss": "scss",
      "html": "html",
      "icons": "icons",
      "assets": "assets"
    }
  },
  "plugins": {
    "scss": {
      "dirAttribute": "dir",
      "htmlIsRootElement": true,
      "cleancss": true
    },
    "html": {
      "beautify": {},
      "minifier": {},
      "cheerio": {
        "decodeEntities": false
      },
      "customTypeHandlers": {
          "mustache": {
              "transformer": "./mustache/transformer",
              "includeHandler": "./mustache/handler",
              "dev": false
          }                 
      },
      "replaceAmpToSymbol": true,
      "cleancss": {},
      "relativeSrc": false,
      "deleteFromDist": false
    },
    "icons": {
      "startCodepoint": 61696,
      "sprites": {
        "className": "sprite",
        "maxWidth": 70,
        "maxHeight": false
      },
      "svgSprite": {
        "width": "2em",
        "height": "2em",
        "external": false,
        "removeColors": true,
        "className": "svg-icon"
      },
      "fonts": {
        "name": "ungic",
        "fixedWidth": false,
        "fontHeight": 512,
        "centerHorizontally": true,
        "normalize": true,
        "fontWeight": 400,
        "className": "icon",
        "fontSize": "2em",
        "lables": true
      }
    }
  },
  "build": {
    "releases": {
      "default": {
        "saveAllAssets": true,
        "host": "",
        "noConflict": true,
        "urlsOptimization": true,
        "scssBuildName": "default",
        "htmlBuildName": "default",
        "iconsBuildName": "default",
        "includeOnlyUsedComponents": false,
        "combineIcons": true,
        "combineScssComponents": true
      }
    },
    "plugins": {
      "html": {
        "dev": {
          "formatting": "beautify",
          "validation": false
        },
        "release": {
          "configs": {
            "default": {
              "formatting": "beautify",
              "validation": false,
              "includeLocalStyles": false,
              "mergeInternalStyles": false,
              "optimizeInternalStyles": false,
              "includeLocalScripts": false,
              "internalScriptsToFooter": false,
              "externalScriptsToFooter": false,
              "mergeInternalScripts": false,
              "optimizeInternalScripts": false
            }
          },
          "build": {
            "default": {
              "pages": "*",
              "excludePages": [],
              "configId": "default"
            }
          }
        }
      },
      "scss": {
        "dev": {
          "inverse": true,
          "autoprefixer": true,
          "defaultInverse": false,
          "direction": "ltr",
          "oppositeDirection": true,
          "theme": "default"
        },
        "release": {
          "configs": {
            "default": {
              "versionInFilename": true,
              "themeMode": "external",
              "inverseMode": "combined",
              "inverse": true,
              "defaultInverse": false,
              "autoprefixer": true,
              "direction": "ltr",
              "oppositeDirection": true
            }
          },
          "build": {
            "default": {
              "configId": "default",
              "themes": [],
              "defaultTheme": "default",
              "components": "*",
              "excludeComponents": []
            }
          }
        }
      },
      "icons": {
        "dev": {
          "svgIconsMode": "fonts",
          "sprites": true,
          "svgIcons": true
        },
        "release": {
          "configs": {
            "default": {
              "svgIconsMode": "fonts"
            }
          },
          "build": {
            "default": {
              "configId": "default",
              "svgIcons": true,
              "sprites": "**/*.png"
            }
          }
        }
      }
    }
  },
  "verbose": false
}

# name

  • Type: string

  • Default: value from "name" field of package.json file

# version

  • Type: string

  • Default: value from "version" field of package.json file

# mode

# author

  • Type: string
  • Default: value from "author" field of package.json file

# server

  • Type: Object

  • Keys:

    • port Number Default: 2020

# openInBrowser

  • Type: Boolean

  • Default: true

  • Usage:

    Open the start page in the browser after launching the ungic project

# fs (File system)

  • Type: Object

  • Usage:

    Ungic project file structure. The value of each key is a relative path to directories from the configuration file.

    "fs": {
        "dirs": {
            "source": "source",
            "dist": "dist",
            "temp": "temp"
        },
        "dist": {
            "css": "css",
            "fonts": "fonts",
            "img": "img",
            "js": "js"
        },
        "source": {
            "scss": "scss",
            "html": "html",
            "icons": "icons",
            "assets": "assets"
        }
    }
    

    WARNING

    All ungic directories must be in the same directory with the configuration file or be nested in other directories, but cannot be located at a higher level! See example below:

    // Permissible
    "fs": {
        "dirs": {
            "source": "ungic/source",
            "dist": "ungic/public",
            "temp": "temp"
        }
        ...
    
    // Impermissible
        "dirs": {
            "source": "../ungic/source",
            "dist": "../ungic/public",
            "temp": "temp"
        }
        ...
    }
    

# plugins / Basic plugin configuration

  • Type: Object

  • Usage:

    Basic plugin configuration

    "plugins": {
      "scss": {
        ...
      },
      "html": {
        ...
      },
      "icons": {
        ...
      }
    }
    

    Below, you can see all the source configuration schemes for each plugin.

    WARNING

    Below are the source configuration schemas with default values.

# plugins.scss

  • Type: Object

  • Usage:

    Source config scheme
    dirAttribute: {
        type: 'string',
        default: 'dir'
    },
    htmlIsRootElement: {
        type: 'boolean',
        default: true
    },
    generateThemeColorsVars: {
        type: 'boolean',
        default: false
    },
    themeColorsVarsMode: {
        type: 'boolean',
        default: false
    },
    cleancss: {
        "anyOf": [
            {
                type: 'object'
            },
            {
                type: 'boolean'
            }
        ],
        default: true
    }
    

    Explanation:

    ...
    "scss": {    
      // Switch ungic.theme methods of the module to generate variables instead of color
      "themeColorsVarsMode": false,
      // Generate variables for all theme colors (without tints)
      "generateThemeColorsVars": false,
      // DIR attribute
      "dirAttribute": "dir",
      // Make the HTML tag the main element (by default), otherwise you need to use an data-ungic-root attribute
      "htmlIsRootElement": true,
      // Enable processing of clean-css plugin
      "cleancss": true
    }
    

# plugins.html

  • Type: Object

  • Usage:

    Source config scheme
    beautify: {
        type: 'object',
        default: {}
    },  
    minifier: {
        type: 'object',
        default: {}
    },
    cheerio: {
        type: 'object',
        default: {
            decodeEntities: false
        }
    },
    customTypeHandlers: {
        type: 'object',
        patternProperties: {
          "^[A-z_]+\w*$": {
            type: "object",
            required: ["transformer"],
            properties: {
                transformer: {
                    type: "string"
                },
                dev: {
                    type: "boolean",
                    default: false
                },
                includeHandler: {
                    "anyOf": [{
                        type: 'string'
                      },
                      {
                        type: 'boolean'
                      }
                    ]
                }
            }
          }
        }
    },
    dirAttribute: {
        type: 'string',
        default: 'dir'
    },
    replaceAmpToSymbol: {
        type: 'boolean',
        default: true
    },
    cleancss: {
        type: 'object',
        default: {}
    },
    relativeSrc: {
        type: 'boolean',
        default: false
    },
    deleteFromDist: {
        type: 'boolean',
        default: false
    }
    

    Explanation:

    ...
    "html": {
      // Options for the js-beautify plugin 
      // can be used in the root of the config file relative to development mode, 
      // see the mode option for details.
    
      "beautify": {},
    
      // DIR attribute, must be the same as for SCSS plugin.
      "dirAttribute": "dir",
    
      // Options for the html-minifier plugin 
      // can be used in the root of the config file relative to development mode, 
      // see the mode option for details.
      "minifier": {},
      
      // Adding a custom file handler
      "customTypeHandlers": {
          "mustache": {
              // The transformer is applied every time the content of the file has changed. 
              // Should return an asynchronous function which, in turn, 
              // should return the processed value of the file content. 
              // Read more in the plugin HTML documentation.   
              "transformer": "./mustache/transformer",
    
              // A synchronous function that is used to process
              // the contents of a file during inclusion.
              "includeHandler": "./mustache/handler",
    
              // Development mode for includeHandler
              "dev": false
          }                 
      },
    
      // Settings for the cheerio plugin
      "cheerio": {
        "decodeEntities": false
      },
    
      // Replace & on the &
      "replaceAmpToSymbol": true,
    
      // Options for the clean-css plugin 
      // can be used in the root of the config file relative to development mode, 
      // see the mode option for details.
    
      // HTML plugin uses postcss processing of internal document styles
      // when generating a release (Optional).
      "cleancss": {},
    
      // Test option. By default, during development, all paths
      // to styles and resources lead to the local server, 
      // this option allows you to use a relative path instead of links.
      "relativeSrc": false,
    
      // When deleting a document from the source directory, 
      // delete the file from the dist directory as well. 
      // It is not recommended to use this option in order to avoid data loss!
      "deleteFromDist": false
    }
    ...
    

# plugins.icons

  • Type: Object

  • Usage:

    Source config scheme
    {
      startCodepoint: {
        type: 'number',
        default: 61696
      },
      sprites: {
        type: 'object',
        properties: {
          className: {
            type: 'string'
          },
          maxWidth: {
            type: 'number'
          },
          maxHeight: {
            "oneOf": [
              { type: "boolean",  enum:[false]},
              { type: "number" }
            ]
          }
        },
        default: {
          className: 'sprite',
          maxWidth: 70,
          maxHeight: false
        }
      },
      svgSprite: {
        type: 'object',
        properties: {
          className: {
            type: 'string'
          },
          removeColors: {
            type: 'boolean'
          },
          external: {
            type: 'boolean'
          },
          width: {
            "oneOf": [
              { type: "string" },
              { type: "number" }
            ]
          },
          height: {
            "oneOf": [
              { type: "string" },
              { type: "number" }
            ]
          }
        },
        default: {
          width: '2em',
          height: '2em',
          external: false,
          removeColors: true,
          className: 'svg-icon'
        }
      },
      fonts: {
        type: 'object',
        properties: {
          lables: {
              type: 'boolean'
          },
          className: {
            type: 'string'
          },
          name: {
            type: 'string'
          },
          fixedWidth: {
            type: 'boolean'
          },
          fontHeight: {
            type: 'number'
          },
          fontWeight: {
            type: 'number'
          },
          centerHorizontally: {
            type: 'boolean'
          },
          normalize: {
            type: 'boolean'
          },
          fontSize: {
            "oneOf": [
                { type: "string" },
                { type: "number" }
            ]
          }
        },
        default: {
          name: 'ungic',
          fixedWidth: false,
          fontHeight: 512,
          centerHorizontally: true,
          normalize: true,
          fontWeight: 400,
          className: 'icon',
          fontSize: '2em',
          lables: true
        }
      }
    }
    

    Explanation:

    ...
    {
      "icons": {
        "startCodepoint": 61696,
    
        // Configuration for sprites
        "sprites": {
          "className": "sprite",
          "maxWidth": 70,
          "maxHeight": false
        },
    
        // Configuration for SVG sprites
        "svgSprite": {
          "width": "2em",
          "height": "2em",
          "external": false,
          "removeColors": true,
          "className": "svg-icon"
        },
    
        // Configuration for web icon fonts
        "fonts": {
          // Icon font name
          "name": "ungic",
          "fixedWidth": false,
          "fontHeight": 512,
          "centerHorizontally": true,
          "normalize": true,
          "fontWeight": 400,
    
          // Class name
          "className": "icon",
    
          // Base icon size
          "fontSize": "2em",
    
          // To support the accessibility of icons, 
          // it is recommended that you generate titles for them that
          // are visible to screen readers.
          "lables": true
        }
      }
    }
    ...
    

# build

  • Type: Object

  • Usage:

    Plugin settings for project build and release.

# build.releases / Config. release

  • Type: Object

  • Usage:

    This object contains configuration schemas that are used when generating a generic release. The object key is the build_name parameter that is specified in the release command when creating the release, and the value is the object with the release parameters.

    "releases": {
      "{build_name}": {...params}
    }
    

# build.releases[build_name]

  • Usage:

    To generate a release, you need to pass the build_name parameter, this parameter is the key of the releases object, and its value is an object with the release parameters.

    Example of default release configuration:

    ...
    "releases": {
      // default = build_name
      "default": {
        // Move all the files from the assets in the dist directory, otherwise, only the files that are in use will be moved.
        "saveAllAssets": true,
    
        // You can specify a hostname or a relative path.
        // All links in files will be processed relative to the given path.
        "host": "",
    
        // Generate dynamic filenames by adding assembly version to filenames.
        "noConflict": true,
    
        // Optimization of paths.
        "urlsOptimization": true,
    
        // build_name for sass release configuration
        "scssBuildName": "default",
    
        // build_name for html release configuration
        "htmlBuildName": "default",
    
        // build_name for icons release configuration
        "iconsBuildName": "default",
    
        // This option allows you to include in
        // the release only what was used in the project.
    
        // It is worth noting that this option 
        // can only be enabled when the process of including
        // all resources (styles, icons, images) is used directly with the ungic tools.
        // See example below.
        "includeOnlyUsedComponents": false,
    
        // Individual release of icons and styles for each selected release page
        "combineIcons": true,
        "combineScssComponents": true
      }
    }
    ...
    

    An example of using the includeOnlyUsedComponents parameter:

    If we generate a release with the HTML page below for example then in the release, there will be only one home icon, and the features icon will be absent, since this icon was used without the icon handlebars helper, which not only renders the icon, but also registers entry point and snaps the given icon to the current page.

    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <title>Document</title>
    </head>
    <body>
      <a href="#">{{{icon "home"}}} Home page</a>
      <a href="#"><i class="icon icon-features"></i> Home page</a>
    </body>
    </html>
    

    An example of use when building a release using the CLI

    ungic: release --help
    
    ------- System: CLI -------
    | Not enough non-option arguments: got 0, need at least 1
    ---------------------------
    ungic: index.js release <release_name> [version] [build_name]
    
    ungic: release myRelease 1.0 default
    

# build.plugins / Config. plugins for building the project

  • Type: Object

  • Usage:

    This section sets configurations for each plugin that affect the build of the project.

    ...
    {
      "build": {
        "plugins": {
          "html": {
            ...
          },
          "scss": {
            ...
          },
          "icons": {
            ...
          }
        }
      }
    }
    ...
    

    The config object consists of two keys dev and release:

    "icons": {
      "dev": {
        ...
      },
      "release": {
        ...
      }
    }
    

    The dev object specifies the configuration parameters that will be applied in the development environment.

    WARNING

    This configuration is independent of mode build mode (development | production). All development in ungic is done exclusively in dev mode and this does not affect the env process variable.

    The release object specifies the configuration parameters that will be applied in the development environment. This object also consists of two keys configs and build:

    "icons": {
      ...
      "release": {
        "configs": {
        ...
        },
        "build": {
          ...
        }
      }
    }
    

    The build object specifies the release configuration schemes, the object key is a value for build_name parameter

    ungic: icons
    ungic icons: release --help
    ungic icons: index.js release <release_name> [build_name]
    

    The configs object contains the configuration parameters of the release, and the release refers to this config

    Example:

    "icons": {
      ...
      "release": {
        "configs": {
        "main": {
          ...
        }
        },
        "build": {
          "configId": "main",
          ...
        }
      }
    }
    

# build.plugins.html

  • Type: Object

  • Usage:

    The configuration used by the html plugin.

    Source config scheme
    dev: {
      type: "object",
      properties: {
        formatting: {
          "anyOf": [{
              type: 'string',
              enum: ['minifier', 'beautify']
            },
            {
              type: 'boolean',
              enum: [false]
            }
          ]
        },
        validation: {
          type: 'boolean'
        }
      },
      default: {
        formatting: 'beautify',
        validation: false
      }
    },
    release: {
      properties: {
        configs: {
          type: 'object',
          patternProperties: {
            "^[A-z_]+\w*$": {
              type: "object",
              properties: {
                formatting: {
                  "anyOf": [{
                      type: 'string',
                      enum: ['minifier', 'beautify']
                    },
                    {
                      type: 'boolean',
                      enum: [false]
                    }
                  ]
                },
                validation: {
                  type: 'boolean'
                },
                includeLocalStyles: {
                  type: 'boolean'
                },
                mergeInternalStyles: {
                  type: 'boolean'
                },
                optimizeInternalStyles: {
                  type: 'boolean'
                },
                includeLocalScripts: {
                  type: 'boolean'
                },
                internalScriptsToFooter: {
                  type: 'boolean'
                },
                externalScriptsToFooter: {
                  type: 'boolean'
                },
                mergeInternalScripts: {
                  type: 'boolean'
                },
                optimizeInternalScripts: {
                  type: 'boolean'
                }
              }
            }
          }
        },
        build: {
          type: "object",
          patternProperties: {
            "^[A-z_]+\w*$": {
              type: "object",
              required: ['configId', 'pages'],
              properties: {
                version: {
                  type: 'string'
                },
                configId: {
                  type: "string",
                  default: "default"
                },
                pages: {
                  "anyOf": [{
                      type: "array",
                    },
                    {
                      type: "string",
                      enum: ["*"]
                    }
                  ]
                },
                excludePages: {
                  type: 'array'
                }
              }
            }
          },
          additionalProperties: false
        }
      },
      default: {
        configs: {
          default: {
            formatting: 'beautify',
            validation: false,
            includeLocalStyles: false,
            mergeInternalStyles: false,
            optimizeInternalStyles: false,
            includeLocalScripts: false,
            internalScriptsToFooter: false,
            externalScriptsToFooter: false,
            mergeInternalScripts: false,
            optimizeInternalScripts: false
          }
        },
        build: {
          default: {
            pages: "*",
            excludePages: [],
            configId: "default"
          }
        }
      }
    }
    

    Explanation:

    // config in development mode
    "dev": {
      // Formatting type
      "formatting": "beautify",
    
      // Check for HTML validity and generate a report
      "validation": false
    },
    // Release configurations.
    "release": {
      "configs": {
        // Configuration with "default" name
        "default": {
          // Formatting type
          // - beautify
          // - minifier
          "formatting": "beautify",
    
          // Check for HTML validity and generate a report
          "validation": false,
    
          // Include external css styles in the internal? (Affects local files only)
          "includeLocalStyles": false,
    
          // Combine inner styles?
          "mergeInternalStyles": false,
    
          // Optimize inner styles?
          "optimizeInternalStyles": false,
    
          // Include external js scripts in the internal? (Affects local files only)
          "includeLocalScripts": false,
    
          // Move internal scripts to the footer?
          "internalScriptsToFooter": false,
    
          // Move external scripts to the footer?
          "externalScriptsToFooter": false,
    
          // Combine internal scripts?
          "mergeInternalScripts": false,
    
          // Optimize internal scripts?
          "optimizeInternalScripts": false
        }
      },
      "build": {
        "default": {
    
          // pages to generate, an asterisk is supported to select all pages.
          "pages": "*",
    
          // If an asterisk is specified in pages, you can specify exceptions here
          "excludePages": [],
    
          // Here we specify the name of the configuration
          "configId": "default"
        }
      }
    }
    

    WARNING

    From the configuration above, when selecting html pages for the release, the pages key is used, the value of which can be an asterisk * or an array with relative paths from the source working folder of the HTML plugin, by default: source/html/

# build.plugins.scss

  • Type: Object

  • Usage:

    The configuration used by the scss plugin.

    Source config scheme
    dev: {
      type: "object",
      required: ['theme'],
      properties: {
        theme: {
          type: "string"
        },
        autoprefixer: {
          type: "boolean",
          default: true
        },
        inverse: {
          type: "boolean"
        },
        defaultInverse: {
          type: "boolean"
        },
        direction: {
          type: "string",
          enum: ["ltr", "rtl"]
        },
        oppositeDirection: {
          type: "boolean"
        }
      },
      default: {
        inverse: true,
        autoprefixer: true,
        defaultInverse: false,
        direction: 'ltr',
        oppositeDirection: true,
        theme: 'default'
      }
    },
    release: {
      properties: {
        configs: {
          type: 'object',
          patternProperties: {
            "^[A-z_]+\w*$": {
              type: "object",
              required: ['autoprefixer', 'inverse', 'defaultInverse',
              'themeMode', 'inverseMode', 'direction', 'oppositeDirection'],
              properties: {
                versionInFilename: {
                  type: 'boolean'
                },
                autoprefixer: {
                  type: "boolean",
                  default: true
                },
                inverse: {
                  type: "boolean"
                },
                defaultInverse: {
                  type: "boolean"
                },
                themeMode: {
                  type: "string",
                  enum: ["combined", "external"]
                },
                inverseMode: {
                  type: "string",
                  enum: ["combined", "external"]
                },
                direction: {
                  "anyOf": [{
                      type: "string",
                      enum: ["ltr", "rtl"]
                    },
                    {
                      type: "boolean",
                      enum: [false]
                    }
                  ]
                },
                oppositeDirection: {
                  type: "boolean"
                }
              }
            }
          },
          additionalProperties: false
        },
        build: {
          type: "object",
          patternProperties: {
            "^[A-z_]+\w*$": {
              type: "object",
              required: ['components', 'configId'],
              properties: {
                configId: {
                  type: "string",
                  default: "default"
                },
                defaultTheme: {
                  type: "string"
                },
                themes: {
                  "anyOf": [{
                      type: "array",
                    },
                    {
                      type: "boolean",
                      enum: [false]
                    },
                    {
                      type: "string",
                      enum: ["*"]
                    }
                  ]
                },
                version: {
                  type: 'string'
                },
                excludeComponents: {
                  type: 'array'
                },
                components: {
                  "anyOf": [{
                      type: "array",
                    },
                    {
                      type: "string",
                      enum: ["*"]
                    }
                  ]
                }
              }
            }
          },
          additionalProperties: false
        }
      },
      default: {
        configs: {
          default: {
            themeMode: "external",
            inverseMode: "combined",
            versionInFilename: true,
            inverse: true,
            defaultInverse: false,
            autoprefixer: true,
            direction: 'ltr',
            oppositeDirection: true
          }
        },
        build: {
          default: {
            configId: "default",
            themes: [],
            defaultTheme: "default",
            components: "*",
            excludeComponents: []
          }
        }
      }
    }
    

    Explanation:

    "scss": {
      // Config in development mode
      "dev": {
        // Generate inversion?
        "inverse": true,
    
        // Processing by the autoprefixer plugin
        "autoprefixer": true,
    
        // Inversion by default?
        "defaultInverse": false,
    
        // direction by default (ltr|rtl)
        "direction": "ltr",
    
        // Generate the opposite direction? (LTR -> RTL, RTL -> LTR)
        "oppositeDirection": true,
    
        // Theme in development mode
        "theme": "default"
      },
    
      // Release configuration
      "release": {
        "configs": {
          "default": {
            // The version of the file is specified in the file name, 
            // required to avoid caching.
            "versionInFilename": true,
    
            // Method for generating a .css files for themes
            // - external
            // - combined
            "themeMode": "external",
    
            // Method for generating a .css files for inverse themes
            // - external
            // - combined
            "inverseMode": "combined",
    
            // Generate inversion?
            "inverse": true,
    
            //  Inversion by default?
            "defaultInverse": false,
    
            // Processing by the autoprefixer plugin
            "autoprefixer": true,
    
            // direction by default (ltr|rtl)
            "direction": "ltr",
    
            // Generate the opposite direction? (LTR -> RTL, RTL -> LTR)
            "oppositeDirection": true
          }
        },
        "build": {
          "default": {
            // Config ID
            "configId": "default",
    
            // Themes to be included in the project
            "themes": [],
    
            // Theme by default
            "defaultTheme": "default",
    
            // Components that will be compiled into a single release.
            // Asterisk * - all components
            "components": "*",
    
            // If components - * (asterisk), then exceptions are indicated here
            "excludeComponents": []
          }
        }
      }
    }
    

    TIP

    Note! In development mode, the configuration for the dev parameter can be assigned and changed in real time for each component, without having to reload the project! More details in this section. (Russian only)

    In development mode, dev configuration can be defined individually for each component in the index.scss file using the following syntax:

    // index.scss
    
    /* ::::
    inverse: false
    autoprefixer: true
    theme: darkela
    */
    
    @forward ".core";
    

# build.plugins.icons

  • Type: Object

  • Usage:

    The configuration used by the icons plugin.

    Source config scheme
    dev: {
      type: "object",
      properties: {
        svgIconsMode: {
          type: 'string',
          enum: ["svgSprite", "fonts"]
        },
        svgIcons: {
          type: "boolean"
        },
        sprites: {
          type: "boolean"
        }
      },
      default: {
        svgIconsMode: 'fonts',
        sprites: true,
        svgIcons: true
      }
    },
    release: {
      properties: {
        configs: {
          type: 'object',
          patternProperties: {
            "^[A-z_]+\w*$": {
              type: "object",
              properties: {
                svgIconsMode: {
                  type: 'string',
                  enum: ["svgSprite", "fonts"]
                }
              }
            }
          }
        },
        build: {
          type: "object",
          patternProperties: {
            "^[A-z_]+\w*$": {
              type: "object",
              required: ['configId'],
              properties: {
                version: {
                  type: 'string'
                },
                configId: {
                  type: "string"
                },
                svgIcons: {
                  "anyOf": [{
                      type: "string"
                    },
                    {
                      type: "array"
                    },
                    {
                      type: "boolean"
                    }
                  ]
                },
                sprites: {
                  "anyOf": [{
                      type: "string"
                    },
                    {
                      type: "array"
                    },
                    {
                      type: "boolean"
                    }
                  ]
                }
              }
            }
          },
          additionalProperties: false
        }
      },
      default: {
        configs: {
          default: {
            svgIconsMode: 'fonts'
          }
        },
        build: {
          default: {
            configId: 'default',
            svgIcons: true,
            sprites: '**/*.png'
          }
        }
      }
    }
    

    Explanation:

    // Config in development mode
    "dev": {
      // SVG icon generation mode
      // - fonts 
      // - svgSprite
      "svgIconsMode": "fonts",
    
      // Generate sprite from images (.jpg, .png)?
      "sprites": true,
    
      // Generate svg icons?
      "svgIcons": true
    },
    
    // Release configuration
    "release": {
      "configs": {
        "default": {
          // SVG icon generation mode
          "svgIconsMode": "fonts"
        }
      },
      "build": {
        "default": {
          "configId": "default",
          // Generate SVG icons?
            // boolean (true) - generate all icons
            // array - generate specific icons. Must specify ID icons!
            // string - glob pattern relative to the source directory
          "svgIcons": true,
    
          // Generate sprite from raster icons?
            // boolean (true) - generate all raster icons
            // array - generate specific icons. Must specify ID icons!
            // string - glob pattern relative to the source directory
          "sprites": "**/*.png"
        }
      }
    }
    

    WARNING

    When using an array as a value for the svgIcons and sprites parameters, you must specify the ID of icons. ID of icons can be viewed in the icons CLI menu using the icons or search commands, as well as when generating a handlebars template:

    {{{include "templates/ungic-icons.hbs" icons=true}}}
    
    // templates/ungic-icons.hbs
    
    {{{debug}}}
    

    TIP

    The SVG icon generation mode can be changed using the svgmode [mode] command in the CLI icons menu:

    ungic icons: svgmode // Get active mode
    
    ------- System -------
    | Active svgIcons mode: fonts
    ----------------------
    
    ungic icons: svgmode svgSprite // Change mode
    
    ------- System -------
    | Icons generation mode switched to svgSprite!
    ----------------------