# Kit Package API

Details about the Kit Package API for managing Font Awesome kits programmatically.

> Font Awesome Kits can now be installed using npm-compatible package managers. Learn about what's included and how to use the package in JavaScript and other applications.

Make sure you:

- You have a project based setup using[ a modern package manager](/web/setup/packages.md#supported-package-managers)
- [Configured access](/web/setup/packages.md) to use Font Awesome packages.
- [Set up a Kit](/web/setup/use-kit.md) and [Enabled Package Installation](/web/setup/use-kit.md#enable-package-installation-for-your-kit) to use [Pro+ icons](https://fontawesome.com/search?ic=pro-plus-collection).

## What's in the package

| Asset                     | Location     | What it's good for                                                                                                                                                       |
| ------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CSS                       | `css/*`      | StyleSheets ready to work in any modern browser using the files in `webfonts` directory                                                                                  |
| SCSS                      | `scss/*`     | SCSS (Sass) files using the `webfonts` directory                                                                                                                         |
| Webfont Files             | `webfonts/*` | WOFF2 webfont files for use with CSS and SCSS                                                                                                                            |
| Auto loading JavaScript   | `js/*`       | Easier to use JavaScript files for including in `<script>` tags directly in the browser using SVG + JS technology                                                        |
| ESM & CommonJS JavaScript | `modules/*`  | [SVG Core-compatible](/web/dig-deeper/svg-core.md) JavaScript files suitable for use with build tools, JS frameworks, or `<script type="module">` using SVG + JS technology |
| SVG Sprites               | `sprites/*`  | SVG Sprites for all icons                                                                                                                                                |
| SVG Files                 | `svg/*`      | Individual SVG files for all icons                                                                                                                                       |
| Data files                | `metadata/*` | JSON and Yaml files containing icon data                                                                                                                                 |

## Using the JavaScript API

  <h4>
    A modern package for a modern world
  </h4>

The Kit Package uses the newer <code>exports</code> feature of <site-link
to="https://nodejs.org/api/packages.html#exports">package.json configurations</site-link>. Most newer build tools and
systems understand this but older tools may struggle to find modules you try to import.

### `byPrefixAndName[prefix][iconName]`

This object contains all icons in a Kit. If you've [**set your Kit's Icon Selection to subset "By Icon"**](/web/setup/use-kit.md#by-icon-or-by-style-subsetted-kits) this can be easy to understand and use.

_Replace KIT_CODE with your Pro Kit unique token in the examples below._

If you've added the ["house icon"](https://fontawesome.com/icons/house?ip=classic&s=solid) to your Kit, you could do the following.

```js
import { byPrefixAndName } from '@awesome.me/kit-KIT_CODE/icons'

byPrefixAndName.fas['house']
```

Objects from `byPrefixAndName` are organized by prefix, then icon name.

```js
byPrefixAndName.fas['house']
byPrefixAndName.far['square']
byPrefixAndName.fass['sword']
byPrefixAndName.fab['font-awesome']
```

Objects With individual icon objects shaped like this.

```js
// Example icon returned
{
  prefix: 'fas',
  iconName: 'house',
  icon: [
    576,
    512,
    [63498,63500,127968,"home","home-alt","home-lg-alt"],
    'f015',
    'M575.8 255.5c0 18-15 32.1-32 32.1h-32l.7 160.2c0 2.7-.2 5.4-.5 8.1V472c0 22.1-17.9 40-40 40H456c-1.1 0-2.2 0-3.3-.1c-1.4 .1-2.8 .1-4.2 .1H416 392c-22.1 0-40-17.9-40-40V448 384c0-17.7-14.3-32-32-32H256c-17.7 0-32 14.3-32 32v64 24c0 22.1-17.9 40-40 40H160 128.1c-1.5 0-3-.1-4.5-.2c-1.2 .1-2.4 .2-3.6 .2H104c-22.1 0-40-17.9-40-40V360c0-.9 0-1.9 .1-2.8V287.6H32c-18 0-32-14-32-32.1c0-9 3-17 10-24L266.4 8c7-7 15-8 22-8s15 2 21 7L564.8 231.5c8 7 12 15 11 24z'
  ]
};
```

### Prefix

The prefix determines what family and style an icon will render in. Below is a list of prefixes organized per Icon Pack.

#### Kit Custom

| Style                                        | Availability                              | Prefix |        |
| -------------------------------------------- | ----------------------------------------- | ------ | :----: |
| [Kits](https://fontawesome.com/kits)         | [Pro Plan](https://fontawesome.com/plans) | `fak`  | &nbsp; |
| [Kits Duotone](https://fontawesome.com/kits) | [Pro Plan](https://fontawesome.com/plans) | `fakd` |        |

  <h4>
    Parity Across Icon Packs
  </h4>

Each Pro+ only style is considered "small batch" and does not have parity with categories or icons in our larger Packs. Instead they contain a curated selection of the 200 most common icons needed for app and website design.

### `all[]`

All is an array of every icon for a Kit. **This is best if the Kit's Icon Selection is set to subset "By Icon".**

```js
import { all } from '@awesome.me/kit-KIT_CODE/icons'
```

The most useful way to use `all` is to pair it with the SVG Core Library. The
library allows you to register icons you wish to use and look them up in a
variety of ways through other APIs and libraries.

```js
import { library } from '@fortawesome/fontawesome-svg-core'
import { all } from '@awesome.me/kit-KIT_CODE/icons'

library.add(...all)
```

The individual icons in the `all` Array are just like the objects returned from `byPrefixAndName`.

## Icon Packs

One step down from using `all` is to import icons by their **family** and **style**.

```js
import { library } from '@fortawesome/fontawesome-svg-core'
import { fas, fad, fasr, fak } from '@awesome.me/kit-KIT_CODE/icons'
library.add(fas, fad, fal)
```

Icon packs are objects keyed from icon names. But the icon names are prefixed
with `fa` and camel-cased. So `square-check` becomes `faSquareCheck`. Since
variable names in JavaScript cannot begin with numbers that's why you see
everything starting with `fa`.

```js
import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@awesome.me/kit-KIT_CODE/icons'

library.add(fas.faSquareCheck)
```

### Importing from Icon Packs

Using a [prefix](/web/dig-deeper/kit-package-api.md#prefix), you can import an individual styles for use.

```js
// import classic solid, regular, and light
import { fas } from '@awesome.me/kit-KIT_CODE/icons'
import { far } from '@awesome.me/kit-KIT_CODE/icons'
import { fal } from '@awesome.me/kit-KIT_CODE/icons'

// import sharp solid, regular, and light
import { fass } from '@awesome.me/kit-KIT_CODE/icons'
import { fasr } from '@awesome.me/kit-KIT_CODE/icons'
import { fasl } from '@awesome.me/kit-KIT_CODE/icons'

// import brands
import { fab } from '@awesome.me/kit-KIT_CODE/icons'

// import custom icons
import { fak } from '@awesome.me/kit-KIT_CODE/icons'
```

  <h4>
    Shaking Those Trees
  </h4>

Using `all` and icon packs make it hard for build tools to utilize **tree shaking**. So if that's something you know you
want to use, try using the "Individual icons" import examples below. However, you can accomplish the same goal as
tree-shaking by using a Kit that is subset "By Icon". When you set the Kit's Icon Selection to "By Icon", your Kit will only include the icons you select to include. That's the same goal tree-shaking solves but in a less
technically-focused way.

## Individual icons

You can import individual icons. This has the advantage of being tree-shakable for keeping your bundles small. To do so...

1. Provide the `fa`-prefixed, camel-cased format of the icon you want to import's name (e.g. `user` -> `faUser`)
2. Include the path with the [family and style](/web/dig-deeper/styles.md) the icon should render in (e.g. `sharp/thin` for Sharp Thin)

```js
// import user icon in classic, regular, and light
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/classic/solid'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/classic/regular'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/classic/light'

// import user icon in sharp solid, regular, and light
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/sharp/solid'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/sharp/regular'
import { faUser } from '@awesome.me/kit-KIT_CODE/icons/sharp/light'

// import Font Awesome and Web Awesome brands
import { faFontAwesome } from '@awesome.me/kit-KIT_CODE/icons/brands'
import { faWebAwesome } from '@awesome.me/kit-KIT_CODE/icons/brands'

// import custom icon
import { faMyIcon } from '@awesome.me/kit-KIT_CODE/icons/kit/custom`
```

## Troubleshooting

### TypeScript

If you run into import errors when using TypeScript you may need to adjust your TypeScript config.

A common error caused by having the wrong `moduleResolution` is this.

```
Cannot find module '@awesome.me/kit-KIT_CODE/icons/classic/solid' or its corresponding type declarations.
```

To fix this, go into your `tsconfig.json` file and make sure the `moduleResolution` is set to value supported by the kit package.

| Options     |                                                                                                                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nodenext    | Recommended                                                                                                                                                                                         |
| bundler     | Also supported if nodenext does not work for you for some reason.                                                                                                                                   |
| node16      | Supported but not recommended because it is currently the same as nodenext and nodenext is forward looking and will be updated to support new Node.js module resolution features as they are added. |
| ~~node~~    | Unsupported                                                                                                                                                                                         |
| ~~classic~~ | Unsupported                                                                                                                                                                                         |
| ~~node10~~  | Unsupported                                                                                                                                                                                         |

```js
"moduleResolution": "bundler",
```

### Note about incompatible TypeScript defaults

Your TypeScript implementation may default to an incompatible `module` or `moduleResolution` option. For example, as of TypeScript `5.4.2` a new project will default to using `module: commonjs` and will not specify `moduleResolution`. Unfortunately, when `module` is "commonjs", then the default `moduleResolution` is "node10", equivalent to "node", which is not supported.

For more information about the `moduleResolution` setting, see the [official TypeScript docs](https://www.typescriptlang.org/docs/handbook/modules/theory.html#module-resolution-is-host-defined).

### TypeScript + SVG Core APIs

Currently there two functions [in the API](/apis/javascript.md) from `@fortawesome/fontawesome-svg-core` that are affected by a Kit Package.

- [`icon()`](/apis/javascript/methods.md#iconicondefinition-params)
- [`findIconDefinition()`](/apis/javascript/methods.md#findicondefinitionparams)

Because the Kit Package can have a subset of Font Awesome icons or even custom uploaded icons, the TypeScript definitions need to be modified to be aware of these types.

Here, we can see TypeScript is reporting errors with the following code.

```ts
import { icon, findIconDefinition } from '@fortawesome/fontawesome-svg-core'
import type { IconLookup } from '@awesome.me/kit-KIT_CODE/icons'

const lookup: IconLookup = { prefix: 'fas', iconName: 'starship' }

icon(lookup)

findIconDefinition(lookup)
```

```
# tsc
index.ts:13:6 - error TS2345: Argument of type 'IconLookup' is not assignable to parameter of type 'IconLookup | IconName'.
  Type 'import("/path/node_modules/@awesome.me/kit-KIT_CODE/icons/modules/icon-types").IconLookup' is not assignable to type 'import("/path/node_modules/@fortawesome/fontawesome-common-types/index").IconLookup'.
    Types of property 'iconName' are incompatible.
      Type 'import("/path/node_modules/@awesome.me/kit-KIT_CODE/icons/modules/icon-types").IconName' is not assignable to type 'import("/path/node_modules/@fortawesome/fontawesome-common-types/index").IconName'.
        Type '"my-custom-icon"' is not assignable to type 'IconName'.?

13 icon(lookup);
        ~~~~~~

index.ts:15:20 - error TS2345: Argument of type 'import("/path/node_modules/@awesome.me/kit-KIT_CODE/icons/modules/icon-types").IconLookup' is not assignable to parameter of type 'import("/path/node_modules/@fortawesome/fontawesome-common-types/index").IconLookup'.

15 findIconDefinition(lookup);
                      ~~~~~~
```

This can be pretty confusing the first time you run into it. TypeScript is
basically telling us that the arguments for `icon()` or `findIconDefinition()`
have been defined in the `@fortawesome/fontawesome-common-types` package. That
package is generic and includes every available Font Awesome icon. It's not
aware of the icons in _your_ Kit.

We can use [Module Augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to update the definition for both functions.

```diff ts
  import { icon, findIconDefinition } from "@fortawesome/fontawesome-svg-core";
- import type { IconLookup } from "@awesome.me/kit-d1e13f5422/icons";
+ import type { IconLookup, IconName } from "@awesome.me/kit-d1e13f5422/icons";

+ import type { IconDefinition } from "@fortawesome/fontawesome-common-types";

+ declare module "@fortawesome/fontawesome-svg-core" {
+   export function icon(icon: IconName | IconLookup, params?: IconParams): Icon;
+   export function findIconDefinition(iconLookup: IconLookup): IconDefinition;
+ }

  const lookup : IconLookup = { prefix: "fas", iconName: "starship" };

  icon(lookup);

  findIconDefinition(lookup);
```

This will fix things up. You can place the `declare module` in any module (according to our testing) and you only need to add it once.

### 404 Error

If you get this error:

```
HttpErrorGeneral: 404 Not Found - GET https://registry.npmjs.com/@awesome.me%2Fkit-KIT_CODE - Not found
```

Try running the update command before running the install command.

```
npm update '@awesome.me/kit-KIT_CODE'

npm install --save '@awesome.me/kit-KIT_CODE@latest'
```

### Windows NPM Install

Sometimes Windows doesn't play nice with single quotes, so if you are getting path issues after installing, you may need to use double quotes.

```
npm install --save "@awesome.me/kit-[KIT_CODE_GOES_HERE]@latest"
```