Webpack Multifonts Loader

Loader for webpack to generate fontfaces from font families and iconfonts from svgs using webfonts-generator.

Installation

$ npm install multifonts-loader

Use Cases

Set fonts and icons into the MARKUP

<button 
  class="
    icon 
    icon-pig 
    icon-arrow-after 
    font-Roboto-BoldItalic"
>
&nbsp;Click Me&nbsp;
</button>

Set fonts and icons with SASS

@import 'fonts/fonts'
@import 'iconfont/iconfont'
  
button
  @include webfont('Roboto-BoldItalic')
  @include webfont-icon('chicken')
  @include webfont-icon('arrow', 'after')

Customize fonts and icons with SASS

h1
  @include webfont('Arial', 'bold', 'italic')
  @include webfont-icon('lock-close', 'before', 'baseline', '80%')
  &:before
    margin-right: 0.25em

label
  @include webfont('Helvetica-Bold')
  &[for="email"]
    @include webfont-icon('email')
  &[for="password"]
    @include webfont-icon('key')
  &:before
    margin-right: 0.25em

input
  @include webfont('Roboto-LightItalic')

button
  @include webfont('Roboto-BoldItalic')
  @include webfont-icon('lock', 'after', 'baseline', '16px', 'bold', 'normal')
  &:after
    margin-left: 0.25em

Syntax

Set fonts and icons into the MARKUP

*.html

<span class="[FONT_CLASS_PREFIX]-[FONT_FILE_NAME]"></span>

<span class="[ICON_BASE_SELECTOR] [ICON_CLASS_PREFIX]-[SVG_FILE_NAME]"></span>

<span class="[ICON_BASE_SELECTOR] [ICON_CLASS_PREFIX]-[SVG_FILE_NAME]-after"></span>

NOTE: You can specify the position of the icon by appending the word '-after' to its default selector. By default the icon will be added before.

Example:

<span class="font-Roboto-ThinItalic"></span>

<span class="icon icon-arrow"></span>

<span class="icon icon-arrow-after"></span>

Options

| Name | Required | Default | Description | |-------------------------------------------|----------|---------|------------------------------------------| | FONT_CLASS_PREFIX | true | font- | Specifies the class prefix for the font | | FONT_FILE_NAME | true | '' | Specifies the font-family name | | ICON_BASE_SELECTOR | true | icon | Specifies the base selector for the icon | | ICON_CLASS_PREFIX | true | icon- | Specifies the class prefix for the icon | | SVG_FILE_NAME | true | '' | Specifies the icon name |

Set fonts and icons with SASS

Mixin: webfont

@include webfont('FONT_FILE_NAME', 'FONT_WEIGHT', 'FONT_STYLE')

Example:

@import 'fonts/fonts'

div
  @include webfont('Arial', 'bold', 'italic')
  
p
  @include webfont('Roboto-ThinItalic')

Options

| Name | Required | Default | Type | Description | |----------------------|----------|----------|----------------|----------------------------------------------------------------------------------------------------------------------| | FONT_FILE_NAME | true | '' | {String} | Specifies the name of the font-family to use. For generated fonts the font-family is derived from the font filename. | | FONT_WEIGHT | false | normal | css standard | Sets how thick or thin characters in text should be displayed | | FONT_STYLE | false | normal | css standard | Specifies the font style for a text |

Mixin: webfont-icon

@include webfont-icon('SVG_FILE_NAME', 'ICON_POSITION', 'ICON_ALIGN', 'ICON_SIZE', 'ICON_WEIGHT', 'ICON_STYLE')

Example:

@import 'iconfont/iconfont'

span
  @include webfont-icon('calendar', 'before', 'middle', '16px', 'bold', 'italic')
  @include webfont-icon('arrow', 'after')

Options

| Name | Required | Default | Type | Description | |---------------------|----------|-----------|-------------------|----------------------------------------------------------------------------| | SVG_FILE_NAME | true | '' | {String} | Specifies the name of the icon to use. It is derived from the svg filename | | ICON_POSITION | false | before | [before,after] | The position of the icon relative to the current element | | ICON_ALIGN | false | top | css standard | Specifies the alignment of the icon | | ICON_SIZE | false | inherit | css standard | Specifies the size of the icon | | ICON_WEIGHT | false | normal | css standard | Sets how thick or thin characters in text should be displayed | | ICON_STYLE | false | normal | css standard | Specifies the font style for the icon |

Loader Configuration

Create one or multiple configuration files for your fonts and iconfonts.

multifonts.loader.js

const path = require('path');

module.exports = {
  fonts: {
    files: [
      // '**/*.+(woff|woff2|eot|ttf|otf|svg)',
      '**/*.woff',
      '**/*.woff2',
      '**/*.eot',
      '**/*.ttf',
      '**/*.otf',
      '**/*.svg'
    ],
    inputPath: path.resolve(__dirname, 'assets/fonts'),
    outputPath: 'fonts',
    publicPath: '/',
    fontFilename: '[fontname].[chunkhash].[ext]?[hash]',
    cssDest: path.resolve(__dirname, 'styles/fonts'),
    cssFilename: 'fonts',
    scssDest: path.resolve(__dirname, 'styles/fonts'),
    scssFilename: 'fonts',
    templateOptions: {
      classPrefix: 'font-',
      mixinName: 'webfont'
    }
  },
  icons: {
    files: [
      '**/*.svg',
      'arrow2.svg',
      'subdirectory/animal1.svg',
      'subdirectory/animal2.svg',
      'subdirectory/animal200.svg',
      'subfolder',
      'subdirectory',
      path.resolve(__dirname, '../Icons/svg', 'arrow.svg'),
      path.resolve(__dirname, '../Icons/svg/subdirectory', 'animal1.svg')
    ],
    inputPath: path.resolve(__dirname, 'assets/icons/svg'),
    outputPath: 'iconfont',
    types: ['eot', 'woff', 'woff2', 'ttf', 'svg'],
    order: ['eot', 'woff', 'woff2', 'ttf', 'svg'],
    publicPath: '/',
    fontName: 'IconFont',
    fontFilename: '[fontname].[chunkhash].[ext]?[hash]',
    cssDest: path.resolve(__dirname, 'styles/iconfont'),
    cssFilename: 'iconfont',
    scssDest: path.resolve(__dirname, 'styles/iconfont'),
    scssFilename: 'iconfont',
    templateOptions: {
      baseSelector: 'icon',
      classPrefix: 'icon-',
      mixinName: 'webfont-icon'
    }
  }
};

See below webpack-multifonts-loader#options

The configuration file defines two main sections:

fonts

Responsible to locate and process the font families to generate the respective fontfaces.

Optionally, you can decide to generate the fontfaces CSS and/or the SCSS files to a specified location for you to include in your application.

icons

Responsible to locate and process the svg files to generate the respective iconfonts.

Optionally, you can decide to generate the iconfont CSS and/or the SCSS files to a specified location for you to include in your application.

Webpack Setup

Webpack Rule

{
  test: /multifonts\.loader\.js/, // This is the name of the loader configuration file
  use: [
    MiniCssExtractPlugin.loader,
    'css-loader',
    'multifonts-loader'
  ]
}

Chain the multifonts-loader with the css-loader and MiniCssExtractPlugin.loader to generate the CSS style directly into the Webpack default output path.

Optionally you can also generate the css and scss files to include directly into your application.

See below fonts webpack-multifonts-loader#cssdest

See below fonts webpack-multifonts-loader#scssdest

See below icons webpack-multifonts-loader#cssdest

See below icons webpack-multifonts-loader#scssdest

Loader Options

Extend the loader configuration by including all the available options directly into the rule definition.

See below webpack-multifonts-loader#options

Example:

You can override the fontFilename depending on the environment.

{
  test: /multifonts\.loader\.js/,
  use: [
    MiniCssExtractPlugin.loader,
    'css-loader',
    {
      loader: 'multifonts-loader',
      options: {
          fonts: {
            fontFilename: isDevelopment
              ? '[fontname].[chunkhash].[ext]?[hash]'
              : '[chunkhash].[ext]?[hash]'
             // ...
             // Add any other available option
          },
          icons: {
            fontFilename: isDevelopment
              ? '[fontname].[chunkhash].[ext]?[hash]'
              : '[chunkhash].[ext]?[hash]'
             // ...
             // Add any other available option
          }
      }
    }
  ]
}

See below fonts webpack-multifonts-loader#fontfilename

See below icons webpack-multifonts-loader#fontfilename

Integration

Include the configuration file into your app.

app.js

require('multifonts.loader');

APPENDIX

Options

fonts

fonts: {
    files: [
      // '**/*.+(woff|woff2|eot|ttf|otf|svg)',
      '**/*.woff',
      '**/*.woff2',
      '**/*.eot',
      '**/*.ttf',
      '**/*.otf',
      '**/*.svg'
    ],
    inputPath: path.resolve(__dirname, 'assets/fonts'),
    outputPath: 'fonts',
    publicPath: '/',
    fontFilename: '[fontname].[chunkhash].[ext]?[hash]',
    cssDest: path.resolve(__dirname, 'styles/fonts'),
    cssFilename: 'fonts',
    scssDest: path.resolve(__dirname, 'styles/fonts'),
    scssFilename: 'fonts',
    templateOptions: {
      classPrefix: 'font-',
      mixinName: 'webfont'
    }
}

Options

| Name | Type | Required | Default | |-----------------------------------------------------|------------|----------|----------------------------------| | files | {Array} | true | undefined | | inputPath | {String} | true | undefined | | outputPath | {String} | false | iconfont/ | | publicPath | {String} | false | / | | fontFilename | {String} | false | [fontname].[hash].[ext] | | cssDest | {String} | false | false | | cssFilename | {String} | false | iconfont | | scssDest | {String} | false | false | | scssFilename | {String} | false | iconfont | | fontfaceTemplateCSS | {String} | false | ../templates/fontface-css.hbs | | fontfaceTemplateSCSS | {String} | false | ../templates/fontface-scss.hbs | | templateOptions | {Object} | false | {} | | templateOptions.classPrefix | {String} | false | font- | | templateOptions.mixinName | {String} | false | webfont |

files

Required: true

Type: Array

Default: undefined

The Glob pattern to use to find the font files to process.

inputPath

Required: true

Type: String

Default: undefined

The context for the Glob pattern.

outputPath

Required: false

Type: String

Default: iconfont/

The path relative to the default Webpack output folder where to save the fonts files.

publicPath

Required: false

Type: String

Default: /

This is the URL prefix for the generated font url (e.g. /static/ or https://cdn.project.net/). Should typically match Webpack's config.output.publicPath.

fontFilename

Required: false

Type: String

Default: [fontname].[hash].[ext]

See webfonts-loader#filename-string

The generated font file names. These elements can be used:

• [fontname]: the name of the font file being generated
• [ext]: the extension of the font file being generated (eot, ...)
• [hash]: the hash of the current compilation
• [chunkhash]: the hash of the SVG files

This option can be also configured globally in the webpack loader options.

cssDest

Required: false

Type: String

Default: false

The absolute path to use to save a copy of the CSS file being generated.

If set the CSS file will be generated at the specified destination.

cssFilename

Required: false

Type: String

Default: iconfont

The name CSS file being generated.

scssDest

Required: false

Type: String

Default: false

The absolute path to use to save a copy of the SCSS file being generated.

If set the SCSS file will be generated at the specified destination.

scssFilename

Required: false

Type: String

Default: iconfont

The name SCSS file being generated.

fontfaceTemplateCSS

Required: false

Type: String

Default: ../templates/fontface-css.hbs

The template to use to generate the css.

fontfaceTemplateSCSS

Required: false

Type: String

Default: ../templates/fontface-scss.hbs

The template to use to generate the scss.

templateOptions

Options passed to the fontfaceTemplateCSS and fontfaceTemplateSCSS.

It can be extended to include any custom variables you would like to render in your custom templates.

templateOptions: {
  classPrefix: 'font-',
  mixinName: 'webfont',
  // This options will be passed to the template for you to render
  customOption: 'customValue'
}

classPrefix

Required: false

Type: String

Default: font-

The prefix to use for the font classes being generated.

mixinName

Required: false

Type: String

Default: webfont

The name of the scss mixin to call when including the font.

icons

icons: {
    files: [
      '**/*.svg',
      'arrow2.svg',
      'subdirectory/animal1.svg',
      'subdirectory/animal2.svg',
      'subdirectory/animal200.svg',
      'subfolder',
      'subdirectory',
      path.resolve(__dirname, '../Icons/svg', 'arrow.svg'),
      path.resolve(__dirname, '../Icons/svg/subdirectory', 'animal1.svg')
    ],
    inputPath: path.resolve(__dirname, 'assets/icons/svg'),
    outputPath: 'iconfont',
    types: ['eot', 'woff', 'woff2', 'ttf', 'svg'],
    order: ['eot', 'woff', 'woff2', 'ttf', 'svg'],
    publicPath: '/',
    fontName: 'IconFont',
    fontFilename: '[fontname].[chunkhash].[ext]?[hash]',
    cssDest: path.resolve(__dirname, 'styles/iconfont'),
    cssFilename: 'iconfont',
    scssDest: path.resolve(__dirname, 'styles/iconfont'),
    scssFilename: 'iconfont',
    templateOptions: {
      baseSelector: 'icon',
      classPrefix: 'icon-',
      mixinName: 'webfont-icon'
    }
}

Options

| Name | Type | Required | Default | |-------------------------------------------------------|------------|----------|------------------------------------------| | files | {Array} | true | undefined | | inputPath | {String} | true | undefined | | outputPath | {String} | false | fonts/ | | types | {Array} | false | ['eot', 'woff', 'woff2', 'ttf', 'svg'] | | order | {Array} | false | ['eot', 'woff', 'woff2', 'ttf', 'svg'] | | publicPath | {String} | false | / | | fontName | {String} | false | IconFont | | fontFilename | {String} | false | [fontname].[hash].[ext] | | cssDest | {String} | false | false | | cssFilename | {String} | false | iconfont | | scssDest | {String} | false | false | | scssFilename | {String} | false | fonts | | cssTemplate | {String} | false | ../templates/css.hbs | | scssTemplate | {String} | false | ../templates/scss.hbs | | templateOptions | {Object} | false | {} | | templateOptions.baseSelector | {String} | false | icon | | templateOptions.classPrefix | {String} | false | icon- | | templateOptions.mixinName | {String} | false | webfont-icon |

files

Required: true

Type: Array

Default: undefined

The Glob pattern to use to find the svg files to process.

inputPath

Required: true

Type: String

Default: undefined

The context for the Glob pattern.

outputPath

Required: false

Type: String

Default: fonts/

The path relative to the default Webpack output folder where to save the svg iconfont files.

types

Required: false

Type: Array

Default: ['eot', 'woff', 'woff2', 'ttf', 'svg']

See webfonts-generator#types

order

Required: false

Type: Array

Default: ['eot', 'woff', 'woff2', 'ttf', 'svg']

See webfonts-generator#order

publicPath

Required: false

Type: String

Default: /

See webfonts-loader#publicpath-string

fontName

Required: false

Type: String

Default: IconFont

See webfonts-generator#fontname

fontFilename

Required: false

Type: String

Default: [fontname].[hash].[ext]

See webfonts-loader#filename-string

The generated font file names. These elements can be used:

• [fontname]: the value of the fontName parameter
• [ext]: the extension of the font file being generated (eot, ...)
• [hash]: the hash of the current compilation
• [chunkhash]: the hash of the SVG files

This option can be also configured globally in the webpack loader options.

cssDest

Required: false

Type: String

Default: false

The absolute path to use to save a copy of the CSS file being generated.

If set the CSS file will be generated at the specified destination.

cssFilename

Required: false

Type: String

Default: fonts

The name CSS file being generated.

scssDest

Required: false

Type: String

Default: false

The absolute path to use to save a copy of the SCSS file being generated.

If set the SCSS file will be generated at the specified destination.

scssFilename

Required: false

Type: String

Default: fonts

The name SCSS file being generated.

cssTemplate

Required: false

Type: String

Default: ../templates/css.hbs

The template to use to generate the css.

scssTemplate

Required: false

Type: String

Default: ../templates/scss.hbs

The template to use to generate the scss.

templateOptions

Options passed to the cssTemplate and scssTemplate.

It can be extended to include any custom variables you would like to render in your custom templates.

templateOptions: {
  baseSelector: 'icon',
  classPrefix: 'icon-',
  mixinName: 'webfont-icon',
  // This options will be passed to the template for you to render
  customOption: 'customValue'
}

baseSelector

Required: false

Type: String

Default: icon

The class name for the css being generated.

See webfonts-generator#templateoptions

classPrefix

Required: false

Type: String

Default: icon-

The css class prefix for the css being generated.

See webfonts-generator#templateoptions

mixinName

Required: false

Type: String

Default: webfont-icon

The name of the scss mixin to call when including the icons.

Tests

$ npm run test-build
$ npm run test-dev

Thanks

• Inpired by webfonts-loader
• Made possible by webfonts-generator

Licence

Public domain, see the LICENCE file.