@vesp/nuxt-fontawesome

Module to use Font Awesome 6 icons in your Nuxt 3 project.

This module does not use vue-fontawesome under the hood as dependency, but contains some code from its sources to implement its features with Nuxt Universal Render, also known as ssr: true in config.

The main difference from official component is creating real tags in template instead of rendering nodes in browser. That is why it works on server.

I tried to implement as many features I could (like mask, transform and symbol) but not sure if everything works the same way as in vue-fontawesome.

Please use issues to report problems.

Setup

• Add dependency to your project

npx nuxi@latest module add @vesp/nuxt-fontawesome

• Add some icon packs

npm i -D @fortawesome/free-solid-svg-icons @fortawesome/free-regular-svg-icons @fortawesome/free-brands-svg-icons

• Add @vesp/nuxt-fontawesome to modules in your nuxt.config.ts
• Configure loaded icons

Use the fontawesome key:

  // nuxt.config.ts
  modules: [
    '@vesp/nuxt-fontawesome',
  ],
  fontawesome: {
    icons: {
      solid: ['cog', ...],
      ...
    }
  }
}

Module options

component

• Default: font-awesome

Default component name is <font-awesome icon="" ... />, and you can change that here. For example, if you will specify fa, it will become <fa icon="" ... />. Also see suffix.

useLayers

• Default: true

Boolean to indicate if the layers component should be registered globally. Name of the component will be ${options.component}-layers, and <font-awesome-layers ... /> by default.

useLayersText

• Default: true

Boolean to indicate if the layers component should be registered globally. Name of the component will be the ${options.component}-layers-text, and <font-awesome-layers-text ... /> by default.

icons

Which icons you will use. FontAwesome currently supports up to 5 icon styles in 3 families.

This option is an object with the style names as property and an array with all icon names you wish to use from those styles

  icons: {
    solid: ['coffee', 'child', ... ],
    regular: ['comment', ... ],
    brands: ['twitter', ... ],
  },
  proIcons: {
    solid: [],
    regular: [],
    light: [],
    thin: [],
    duotone: [],
  },
  sharpIcons: {
    solid: [], 
    regular: [],
    light: [],
    thin: [],
  }

addCss

• Default: true

If the module should automatically add the fontawesome styles to the global css config. It works by unshifting @fortawesome/fontawesome-svg-core/styles.css onto the Nuxt css property.

suffix

• Default: true

Boolean whether to append -icon to the icon component name. This option exists as the component name option is also used for the layer components and you might not want to add '-icon' to those.

  // config
  component: 'fa',
  suffix: true

  // usage
  <fa-icon />
  <fa-layers />
  <fa-layers-text />

  // config
  component: 'fa',
  suffix: false

  // usage
  <fa />
  <fa-layers />
  <fa-layers-text />

Usage

You can find more details under playground folder.

• Ensure you have installed an icon package npm i -D @fortawesome/free-solid-svg-icons
• and have added the module configuration to your nuxt.config.js

Default component names are:

• <font-awesome>
• <font-awesome-layers>
• <font-awesome-layers-text>

You can change this names by component option.

  // nuxt.config
  fontawesome: {
    icons: {
      solid: ['dollar-sign', 'cog', 'circle', 'check', 'calendar'],
      regular: ['user']
    }
  }

• Use global icons:

<template>
  <div>
    <font-awesome :icon="['far', 'user']" />
    <font-awesome icon="dollar-sign" style="font-size: 30px" />
    <font-awesome icon="cog" />

    <font-awesome-layers class="fa-4x">
      <font-awesome icon="circle" />
      <font-awesome icon="check" transform="shrink-6" :style="{color: 'white'}" />
    </font-awesome-layers>

    <font-awesome-layers full-width class="fa-4x">
      <font-awesome icon="calendar" />
      <font-awesome-layers-text transform="shrink-8 down-3" value="27" class="fa-inverse" />
    </font-awesome-layers>
  </div>
</template>

<script></script>

• Use locally imported icons

<template>
  <div>
    <font-awesome-layers full-width size="4x">
      <font-awesome :icon="faCircle" />
      <font-awesome-layers-text transform="shrink-12" value="GALSD" class="fa-inverse" />
    </font-awesome-layers>

    <font-awesome :icon="faAddressBook" />
    <font-awesome :icon="faGithub" />
  </div>
</template>

<script setup>
import {faCircle, faAddressBook} from '@fortawesome/free-solid-svg-icons'
import {faGithub} from '@fortawesome/free-brands-svg-icons'
</script>

FontAwesome Kit

You can use kits from Fontawesome Pro.

1. Retrieve your kit ID on FontAwesome: https://fontawesome.com/kits/**KIT_ID**/package (10 alpha-numerics characters)
2. In Settings tab, activate Enable Installing Your Kit as a Package option if not yet done
3. Install, in your local project, your custom kit package as defined in Package tab
4. Update nuxt.config.ts by adding your kit ID under kitIdentifier key and icons required in project under proIcons.kit key:

   // https://nuxt.com/docs/api/configuration/nuxt-config
   export default defineNuxtConfig({
       compatibilityDate: '2024-11-01',
       devtools: { enabled: true },
       modules: [
           '@vesp/nuxt-fontawesome'
       ],
       fontawesome: {
           kitIdentifier: (KIT_ID),
           proIcons: {
               kit: [
                   (ICON_NAME ex: solid-user-circle-exclamation)
               ],
           },
       }
   })
   

5. Use your imported icon in your page like this:

   <font-awesome :icon="['fak', 'solid-user-circle-exclamation']" />
   

License

MIT License

This module was inspired by official Nuxt 2 module from Nuxt Community.

Some code and function was taken from vue-fontawesome repository to implement its features with server rendering.