Web

Using A Package Manager

For those using npm or yarn package managers, you can use the Font Awesome packages to easily keep your project up-to-date with the latest icons and improvements.

Advertisement

We’ll cover the basics of choosing the package that best suits your needs, access configuration, tips for which method to use for adding icons, and more!

1. Configure Access

Advertisement

If you're just using the Free package, you can skip this step.

If you plan to use the Pro packages, which contain more icons and styles, you'll need to have an active subscription to a Pro Plan and a valid Pro Package Token and then follow the steps below to configure Pro access for your project.

Keep It Secret, Keep It Safe!

Your super-secret npm token - TOKEN - is private. Don't share it with anyone who shouldn't have it. (You can find it in your account.)

Now that you've got your package token handy, you'll need to configure the @fortawesome scope to use our Pro npm registry. You can set this up globally or per-project.

Set Up npm Token for All Projects

This global setup will allow any of your projects to use the Font Awesome package and your token. For the global set up, run:

npm config set "@fortawesome:registry" https://npm.fontawesome.com/
npm config set "//npm.fontawesome.com/:_authToken" TOKEN

Set Up npm Token for a Specific Project

This per-project setup lets you configure each project individually, which can be good for teams and CI/CD.

To authenticate when using npm or yarn v1, create a .npmrc file in the root of your project (or wherever your package.json file lives). For yarn v2 you will need to create a .yarnrc.yml file. Then add one of the following snippets to the file.

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=TOKEN

npmScopes:
fortawesome:
  npmAlwaysAuth: true
  npmRegistryServer: "https://npm.fontawesome.com/"
  npmAuthToken: "TOKEN"

Alternate Per-project Setup: Using Environment Variables

You can use npm environment variables in your .npmrc file if you prefer:

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_AUTH_TOKEN}

Per-project Setup for Modern Yarn

Using a .npmrc file works great for Yarn 1.x but for modern Yarn, you'll want to set up a .yarnrc.yml file.

npmScopes:
 fortawesome:
   npmAlwaysAuth: true
   npmRegistryServer: "https://npm.fontawesome.com/"
   npmAuthToken: "TOKEN"

Modern Yarn setup with envrionment variables.

npmScopes:
  fortawesome:
    npmAlwaysAuth: true
    npmRegistryServer: "https://npm.fontawesome.com/"
    npmAuthToken: "${FONTAWESOME_NPM_AUTH_TOKEN}"

Basic Authentication for Proxys

If you're using a proxy, you can use basic authentication in your .npmrc file.

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:username=token
//npm.fontawesome.com/:_password=TOKEN

2. Install Your Package

Advertisement

There are two options to for installing the Font Awesome packages:

Install What You Get
Certain Specific Things You can start with just the core javascript files and then select specific styles of icons. This gives you more control if you plan to use our Javascript API, a Javascript component, tree-shaking, or just want to fine-tune what gets included.
All The Things The Free and Pro packages include not only the icons in all the styles, but also all the supporting files to make them render. We do not recommend using this package. This is a large package and continues to grow. Only use this if you need to use webfont technology

The Pro Package

Once you have global or per-project access setup, you can install the Version 6 Pro package via npm or yarn:

npm install --save @fortawesome/fontawesome-svg-core

# Select the styles you need and install them with the following commands.

npm install --save @fortawesome/free-brands-svg-icons
npm install --save @fortawesome/pro-solid-svg-icons
npm install --save @fortawesome/pro-regular-svg-icons
npm install --save @fortawesome/pro-light-svg-icons
npm install --save @fortawesome/pro-thin-svg-icons
npm install --save @fortawesome/pro-duotone-svg-icons
npm install --save @fortawesome/sharp-solid-svg-icons
npm install --save @fortawesome/sharp-regular-svg-icons
npm install --save @fortawesome/sharp-light-svg-icons

yarn add @fortawesome/fontawesome-svg-core

# Select the styles you need and install them with the following commands.

yarn add @fortawesome/free-brands-svg-icons
yarn add @fortawesome/pro-solid-svg-icons
yarn add @fortawesome/pro-regular-svg-icons
yarn add @fortawesome/pro-light-svg-icons
yarn add @fortawesome/pro-thin-svg-icons
yarn add @fortawesome/pro-duotone-svg-icons
yarn add @fortawesome/sharp-solid-svg-icons
yarn add @fortawesome/sharp-regular-svg-icons
yarn add @fortawesome/sharp-light-svg-icons

npm install --save @fortawesome/fontawesome-pro

yarn add @fortawesome/fontawesome-pro

Or if you're using environment variables, you can do this instead:

FONTAWESOME_NPM_AUTH_TOKEN=TOKENVALUE npm install --save @fortawesome/fontawesome-pro

The Free Package

If you need just the Free icons, we have a slimmed-down free-only package for that. Install with this command:

npm install --save @fortawesome/fontawesome-svg-core

# Select the styles you need and install them with the following commands.

npm install --save @fortawesome/free-solid-svg-icons
npm install --save @fortawesome/free-regular-svg-icons
npm install --save @fortawesome/free-brands-svg-icons

yarn add @fortawesome/fontawesome-svg-core

# Select the styles you need and install them with the following commands.

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

npm install --save @fortawesome/fontawesome-free

yarn add @fortawesome/fontawesome-free

Or if you're using environment variables, you can do this instead:

FONTAWESOME_NPM_AUTH_TOKEN=TOKENVALUE npm install --save @fortawesome/fontawesome-free

3. Pick Your Method and Add Icons

Advertisement

You're all set to reference Font Awesome in your project. You can use either Web Fonts + CSS or SVG + JS to get icons into your projects.

Use Web Fonts + CSS Use SVG + JS

Not sure which to pick? Learn which is right for your project.

4. Cache Your CI Dependencies

Tune your CI to keep your bandwidth usage low. We'll show you how.

5. Troubleshooting Your Configuration

Supported Package managers

Font Awesome supports the following package managers:

Private and Public npm Repositories

Repository Public Require active Pro subscription Font Awesome Pro Font Awesome Free
https://npm.fontawesome.com ❌ ✅ ✅ ✅
https://registry.yarnpkg.com ✅ ❌ ❌ ✅
https://registry.npmjs.org ✅ ❌ ❌ ✅

Note: To use the Private npm Repository, an active subscription to Font Awesome Pro is required.

Configuration Troubleshooting Commands

Use the following commands to get configuration information for your package manager:

  • npm: npm config list
  • classic yarn: yarn config list --verbose
  • modern yarn: yarn config --why (pay attention to npmScopes entry)
  • pnpm: pnpm config list (pay attention to the config from section)

Use the Private Repository

If your application needs to use the private repository, ensure that credentials are set:

npm example output

; "user" config from /path/to/.npmrc
# ...
@fortawesome:registry = "https://npm.fontawesome.com/"
//npm.fontawesome.com/:_authToken = (protected)

classic yarn example output

verbose 0.100133333 Found configuration file "/path/to/.npmrc".
# ...
'@fortawesome:registry': 'https://npm.fontawesome.com/',
'//npm.fontawesome.com/:_authToken': FONT-AWESOME-PACKAGE-FONT-AWESOME-PACKAGE-TOKEN,

modern yarn example output

➤ YN0000: npmScopes                     undefined, /path/to/.yarnrc.yml   Map(1) { 'fortawesome' => Map(6) { 'npmAlwaysAuth' => true, 'npmAuthIdent' => null, 'npmAuthToken' => '********', 'npmAuditRegistry' => null, 'npmPublishRegistry' => null, 'npmRegistryServer' => 'https://npm.fontawesome.com/' } }
# ...

pnpm example output

//npm.fontawesome.com/:_authToken=YOUR_FONTAWESOME_NPM_TOKEN
@fortawesome:registry=https://npm.fontawesome.com/
prefix=/path/to/nodejs/18.13.0/.npm
registry=https://registry.npmjs.org/
user-agent=pnpm/7.29.1 npm/? node/v18.13.0 darwin arm64
# ...

Token in environment variable

It is recommended to store the token in an environment variable in order to avoid to commit it in a public repository.

Make sure that the environment variable is available and readable by the package manager, this may be the cause of authentication issues on remote servers.

Use the Public Repository

If your application needs to use the Public Repository, ensure that the above configuration is not set.

Switching from Private to Public Repository (and vice versa)

When switching from the Private Repository to the Public Repository, remove the currently installed Font Awesome packages from the lock file. The specific command to do this depends on the package manager you are using (yarn or npm).

Per-Project npm Configuration

It is recommended to use per-project npm configuration.

If a global configuration is provided for Font Awesome Pro, it is possible to use per-project configuration for projects that require Font Awesome Free, so that the lock files are not overwritten with references to the Private npm Repository.

# per-project configuration example for `yarn` to force the usage of the Public Repository
@fortawesome:registry=https://registry.yarnpkg.com