Table of contents

• Installation
• Usage
  • Alternative import syntax
  • Automatically rebuild when vue.config.js is modified
• Changelog
• Acknowledgements
• License

Using Font Awesome 5 in a Vue.js project is already pretty simple, but you still have to work with a verbose and repetitive syntax in order to benefit from tree-shaking and include only the needed icons in the final bundle. This tiny plugin allows you to manage your icon sets directly from your vue.config.js file, avoiding boilerplate code and error-prone repetitions.

Installation

vue add @cheap-glitch/fontawesome

The install prompt will ask you which icon sets you want to be automatically included in your package.json and downloaded. You can leave all the options unchecked if you'd rather add them manually. Regardless of your choices, two packages will always be added and downloaded:

• fontawesome-svg-core
• vue-fontawesome

No other file will be modified during the installation process.

Note: if you want to install pro icon sets, make sure you have a .npmrc file at the root of your project with your token in it, otherwise the installation will fail (cf. "Installing the Pro version of Font Awesome").

Usage

// vue.config.js

// The config object should be placed inside 'pluginOptions'
fontawesome: {

    // Defines the name of the Font Awesome component
    // used inside Vue templates (optional, defaults to 'fa')
    component: 'fa-icon',

    // Defines the names of all the Font Awesome
    // components that will be imported (optional)
    components: {
        icon:       'fa-icon',
        layers:     'fa-layers',
        layersText: 'fa-layers-text',
    },

    // Lists the imported icons
    imports: [
        {
            set: '@fortawesome/free-solid-svg-icons',
            icons: [
                'faUser',
                'faFileUpload',
                'faFrenchFries',
            ]
        },
        {
            // You can omit the '@fortawesome/' prefix in the set name
            set: 'pro-duotone-svg-icons',
            icons: [
                // You can omit the 'fa' prefix in the icon names
                'guitar',
                'fax',
                'fastForward',

                // You can also spell the name in kebab case
                'spider-black-widow',

                // Or with spaces
                'dumpster fire',
            ]
        },
        {
            // You can also omit the '-svg-icons' suffix
            set: 'free-brands',
            icons: [
                'faVuejs',
                'creative-commons'
                'Fort Awesome',
            ]
        },
        // Specifying only a name will load the entire icon set
        // WARNING: This is only suitable for the prototyping phase,
        //          as every single icon in the set will be included
        //          in the final bundle!
        'pro-light',
    ]
}

You can then use the Font Awesome components in your templates. For more info, see here.

Alternative import syntax

If you prefer to have all the icons in one list, you can list the imports using a hash map instead of a list sorted by set:

// vue.config.js

fontawesome: {
    imports: {
        // Import an icon from a single set
        github: 'free-brands',

        // Import the same icon from several sets
        userRobot: ['pro-light', 'pro-duotone'],
    }
}

Automatically rebuild when vue.config.js is modified

Unfortunately, Vue CLI doesn't watch edits made on vue.config.js. To get automatic rebuilds, you can use a watcher like nodemon:

"scripts": {
    "serve": "nodemon --watch vue.config.js --exec npm run serve-vue-cli",
    "serve-vue-cli": "vue-cli-service serve"
}

Note that you'll still need to reload the page manually as the WebSocket connection with the local server will be lost.

Changelog

See the full changelog here.

Acknowledgements

This plugin depends on the awesome webpack-inject-plugin.

This plugin is heavily inspired by its Nuxt.js counterpart, nuxt-fontawesome.

License

This software is distributed under the ISC license.