Skip to content

atlowChemi/vite-svg-2-webfont

Repository files navigation

vite-svg-2-webfont

npm GitHub Actions Workflow Status npm license npm bundle size node engine Package Quality

A Vite Plugin that generates fonts from your SVG icons and allows you to use your icons in your HTML.

vite-svg-2-webfont uses the webfonts-generator package to create fonts in any format. It also generates CSS files so that you can use your icons directly in your HTML, using CSS classes.

Installation

NPM

npm i -D vite-svg-2-webfont

YARN

yarn add -D vite-svg-2-webfont

PNPM

pnpm add -D vite-svg-2-webfont

Usage

Add the plugin to the vite.config.ts with the wanted setup, and import the virtual module, to inject the icons CSS font to the bundle.

Vite config

Add the plugin to your vite configs plugin array.

// vite.config.ts
import { resolve } from 'path';
import { defineConfig } from 'vite';
import viteSvgToWebfont from 'vite-svg-2-webfont';

export default defineConfig({
    plugins: [
        viteSvgToWebfont({
            context: resolve(__dirname, 'icons'),
        }),
    ],
});

Import virtual module

Import the virtual module into the app

// main.ts
import 'virtual:vite-svg-2-webfont.css';

Add class-name to HTML element to use font

Use the font in templates with the icon font class and an icon class name. The default font class name is .icon and can be overriden by passing the baseSelector configuration option. Icon class names are derived from their .svg file name, and prefixed with the value of classPrefix which defaults to icon-.

In the below example, the add class would display the icon created from the file {context}/add.svg

<i class="icon icon-add"></i>

Configuration

The plugin has an API consisting of one required parameter and multiple optional parameters allowing to fully customize plugin setup.

context

files

  • type: string
  • description: An array of globs, of the SVG files to add into the webfont, from within the context
  • default ['*.svg']

fontName

  • type: string
  • description: Name of font and base name of font files.
  • default 'iconfont'

dest

  • type: string
  • description: Directory for generated font files.
  • default path.resolve(context, '..', 'artifacts')
  • See webfonts-generator#dest

cssDest

  • type: string
  • description: Path for generated CSS file.
  • default path.join(dest, fontName + '.css')
  • See webfonts-generator#cssdest

cssTemplate

  • type: string

  • description: Path of custom CSS template. Generator uses handlebars templates. Tht template receives options from templateOptions along with the following options:

    • fontName
    • src string – Value of the src property for @font-face.
    • codepoints object - Codepoints of icons in hex format.
  • Paths of default templates are stored in the webfontsGenerator.templates object.

    • webfontsGenerator.templates.css – Default CSS template path. It generates classes with names based on values from options.templateOptions.
    • webfontsGenerator.templates.scss – Default SCSS template path. It generates mixin webfont-icon to add icon styles. It is safe to use multiple generated files with mixins together.
  • See webfonts-generator#csstemplate

cssContext

cssFontsUrl

  • type: string
  • description: Fonts path used in CSS file.
  • default cssDest

htmlDest

htmlTemplate

  • type: string
  • description: HTML template path. Generator uses handlebars templates. Template receives options from options.templateOptions along with the following options:
    • fontName
    • styles string – Styles generated with default CSS template. (cssFontsPath is changed to relative path from htmlDest to dest)
    • names string[] – Names of icons.
  • See webfonts-generator#htmltemplate

ligature

normalize

round

descent

fixedWidth

fontHeight

centerHorizontally

generateFiles

  • type: boolean | string | string[]
  • description: Sets the type of files to be saved to system during development.
  • valid inputs:
    • true Generate all file types.
    • false Generate no files.
    • 'html' - Generate a HTML file
    • 'css' - Generate CSS file
    • 'fonts' - Generate font files (based on the types requested)
  • default false

types

  • type: string | string[]
  • description: Font file types to generate. Possible values:
    • svg
    • ttf
    • woff
    • woff2
    • eot
  • default ['eot', 'woff', 'woff2', 'ttf', 'svg']
  • See webfonts-generator#types

codepoints

  • type: { [key: string]: number }
  • description: Specific code-points for certain icons. Icons without code-points will have code-points incremented from startCodepoint skipping duplicates.
  • See webfonts-generator#codepoints

classPrefix

baseSelector

formatOptions

moduleId

  • type: string
  • description: Virtual module id which is used by Vite to import the plugin artifacts. E.g. the default value is "vite-svg-2-webfont.css" so "virtual:vite-svg-2-webfont.css" should be imported.
  • default 'vite-svg-2-webfont.css'

inline

  • type: boolean
  • description: Inline font assets in CSS using base64 encoding.
  • default false

allowWriteFilesInBuild

  • type: boolean
  • description: Allow outputting assets (HTML, CSS, and Fonts) during build. see
  • default false

Public API

The plugin exposes a public API that can be used inside another plugins using Rollup inter-plugin communication mechanism.

Currently available methods:

getGeneratedWebfonts

  • returns: Array<{ type: 'svg' | 'ttf' | 'woff2' | 'woff' | 'eot', href: string }>
  • description
    • type - a font format generated by a plugin
    • href - a path to a generated font
  • This repo contains the usage example.