Improve documentation to use libraries

[samanthaming]

Feature request

Just wanted to share how I was finally able to add Vue Fontawesome to VuePress. The trick is to add it to enhanceApp.js👍

Here are the exact steps:

1. Install vue-fontawesome (this was pulled from their readme)

yarn add @fortawesome/fontawesome-svg-core
yarn add @fortawesome/free-solid-svg-icons
yarn add @fortawesome/vue-fontawesome
yarn add @fortawesome/free-brands-svg-icons
yarn add @fortawesome/free-regular-svg-icons

2. Register it as a global component (again, the example is from vue-fontawesome readme)

import { library } from '@fortawesome/fontawesome-svg-core'
import { faUserSecret } from '@fortawesome/free-solid-svg-icons'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'

library.add(faUserSecret)

export default ({
  Vue, // the version of Vue being used in the VuePress app
  options, // the options for the root Vue instance
  router, // the router instance for the app
  siteData // site metadata
}) => {
  // ...apply enhancements to the app
  Vue.component('font-awesome-icon', FontAwesomeIcon)
}

3. Now you can use it anywhere in your component 👏

<font-awesome-icon icon="user-secret" />

This took me a while to figure it out 😅. This StackOverflow response was the gamechanger (thank you!) Maybe it's something we can include it in the docs and save folks some time 😊

What problem does this feature solve?

What does the proposed API look like?

How should this be implemented in your opinion?

Are you willing to work on this yourself?

[meteorlxy]

The docs of enhanceApp.js is here:

https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements

Yes it's better to provide more examples for newcomers.

[trolologuy]

I would be happy to contribute to the docs.
But I'm struggling with adding other icons than "user secret".
For example "lightbulb" which is in the repo of fort awesome.
I'm trying to invoke it with <font-awesome-icon icon="lightbulb" /> what am i missing here?

I checked the documentation of '@fortawesome/vue-fontawesome', but many examples are not working (spinner, coffee, ...).

[trolologuy]

Okey after lots of trial and error, I finally managed to get it to work.
In the step 2 of the steps described above, in the enhanceApp.js, you have to register every icon you wish to use (if there are better ways to do that, I'd be happy to know).
For e.g:

import { library } from '@fortawesome/fontawesome-svg-core'
import { faLightbulb, faTools, faLanguage, faGlobeEurope } from '@fortawesome/free-solid-svg-icons'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faFontAwesome, faGithub, faPython } from '@fortawesome/free-brands-svg-icons'

library.add(faLightbulb, faTools, faLanguage, faGlobeEurope, faGithub, faPython)
library.add(faFontAwesome)

export default ({
  Vue, // the version of Vue being used in the VuePress app
  options, // the options for the root Vue instance
  router, // the router instance for the app
  siteData // site metadata
}) => {
  // ...apply enhancements to the app
  Vue.component('font-awesome-icon', FontAwesomeIcon)
}

Allows to use:

<font-awesome-icon icon="language"/>
<font-awesome-icon :icon="['fas', 'tools']"/>
<font-awesome-icon :icon="['fas', 'lightbulb']"/>
<font-awesome-icon :icon="['fab', 'github']" /> <!-- use fab for the brand icons -->

But be aware that some styling options described here won't be available, so it won't display anything.

[mihyunLee]

Hello, first of all, I'm glad I found this contribution.

Currently in my code the font-awesome-icon component is used globally, but the icon is not being rendered.

May I know what the reason is?

1. package.json

"dependencies": {
    "@fortawesome/fontawesome-svg-core": "^6.4.2",
    "@fortawesome/free-brands-svg-icons": "^6.4.2",
    "@fortawesome/free-regular-svg-icons": "^6.4.2",
    "@fortawesome/free-solid-svg-icons": "^6.4.2",
    "@fortawesome/vue-fontawesome": "^3.0.3"
  }

2. .vuepress/enhanceApp.js

import { library } from "@fortawesome/fontawesome-svg-core";
import { faUserSecret } from "@fortawesome/free-solid-svg-icons";
import { FontAwesomeIcon } from "@fortawesome/vue-fontawesome";

library.add(faUserSecret);

export default ({ Vue }) => {
  Vue.component("font-awesome-icon", FontAwesomeIcon);
};

3. .vuepress/components/Home.vue

<template>
  <div>
      <font-awesome-icon icon="user-secret" />
  </div>
</template>

4. An empty path tag is rendered.