README.md 5.35 KB
Newer Older
Raphael Ochsenbein's avatar
Raphael Ochsenbein committed
1
2
3
4
5
6
7
8
9
10
11
12
# Angular Lazy Loaded SVG Icons Library with FontAwesome Icons

Use the cool icons from FontAwesome in your app, fully tree-shaked and only loaded when necessary. Injected into the dom, and therefore IE compatible.

## Live Demo
The live demo can be found at https://font-awesome-icons.akehir.com.

## Getting Started

If you just want to use the library, follow the following 4 simple steps. For contributing, or building the library locally, see the section on [building](#building) the library.

Supported Angular Versions
Raphael Ochsenbein's avatar
Raphael Ochsenbein committed
13
| Angular Version | Library Version |
Raphael Ochsenbein's avatar
Raphael Ochsenbein committed
14
| --------------- | ------------------------ |
Raphael Ochsenbein's avatar
Raphael Ochsenbein committed
15
16
|  9.x            | 1.0.0                    |
| 10.x            | 2.0.0                    |
Raphael Ochsenbein's avatar
Raphael Ochsenbein committed
17
| 11.x            | 3.0.0                    |
18
| 12.x            | 4.0.0                    |
Raphael Ochsenbein's avatar
Raphael Ochsenbein committed
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

### Step 1: Install

Install the npm package.

```
npm i @triangular/font-awesome-icons
```

### Step 2: Add to NgModule Imports

Then, add the __FontAwesomeIconsModule__ to the imports of your module(s).

```typescript
import { NgModule } from '@angular/core';
import { FontAwesomeIconsModule } from '@triangular/font-awesome-icons';

@NgModule({
    declarations: [
    ],
    imports: [
      FontAwesomeIconsModule,
    ],
    providers: [],
    bootstrap: [],
})
export class AppModule { }
```

### Step 3: Register the Icons in the Registry
The tree-shaking magic happens when you import icons from   __@triangular/font-awesome-icons/icons__ and register them in the  __FontAwesomeIconsRegistry__. By explicitly importing the icons where they are required, the tree shaking can ensure they are loaded when they are needed. If an icon is not required, it will not be bundled in your application. If an icon is required in a feature module, it will be bundled with the feature module. And if the icon is bundled in multiple feature modules, it will be bundled with the common bundle - in order to not download the same icon multiple times.

```typescript
import { Component } from '@angular/core';
import { FontAwesomeIconsRegistry } from '@triangular/font-awesome-icons';
import {
  fontAwesomeIconAnkh,
  // add more icons here
} from '@triangular/font-awesome-icons/icons';

@Component({
  selector: 'app-some-component-with-icons',
  template: '<font-awesome-icon name="ankh"></font-awesome-icon>',
  styles: 'svg { color: #ccc; fill: currentColor; width: 5rem; height: 5rem; }',
})
export class SomeComponentWithIcons {

  constructor(private registry: FontAwesomeIconsRegistry) {
    registry.registerIcons([
      fontAwesomeIconAnkh,
      // add more icons here
    ]);
  }
}
```

### Step 4: Enjoy using the Icons with a Peace of Mind
Once an icon has been registered, it can simply be used in your template. If you get the error `can't bind to 'name' since it isn't a known property of 'font-awesome-icon'`, you need to include the __FontAwesomeIconsModule__ in your module. 

```html
<font-awesome-icon name="ankh"></font-awesome-icon>
```

## Building
As a pre-requisite to build the library, you need to install all the dependencies via `npm install` or `yarn`.
Furthermore, you will need to sync the projects submodules `git submodule sync --recursive` and  `git submodule update --init --recursive`.

### Building the Library
Before the sample app can be run, you need to build the library itself.

```
npm run build:lib
```

### Building the Sample App
After building the library, it is either possible to build the sample app, via

```
npm run build:app
```

,or to run the sample app with a local dev server:

```
npm run start:app
```

### Checking the bundle of the Sample App
You can verify how the application is bundled with the following command:

```
npm run analyze
```

## Running the tests

### Unit Tests
There are not many tests, but those that are can be run with:

```
npm run test -- --no-watch --progress=false --code-coverage --browsers ChromeHeadless
```

### And coding style tests

The project follows the [angular style guide](https://angular.io/guide/styleguide) and lints with the following command:

```
npm run lint
```

## Built With

* [Angular](https://github.com/angular/angular) - The web framework used
* [NPM](https://www.npmjs.com/) - Dependency Management
* [Gitlab](https://git.akehir.com) - Source Control & CI Runner

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

We use [SemVer](http://semver.org/) for versioning. 

### Version History

- 1.0.0: Initial Release

## Authors

* **Raphael Ochsenbein** - *Initial work* - [Akehir](https://github.com/akehir)

See also the list of [contributors](https://github.com/akehir/font-awesome-icons/contributors) who participated in this project.

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details

## Acknowledgments

* [FontAwesome (FortAwesome)](https://github.com/FortAwesome/Font-Awesome) for creating the awesome icon library
* [Kevin Kreuzer (kreuzerk)](https://medium.com/angular-in-depth/how-to-create-a-fully-tree-shakable-icon-library-in-angular-c5488cf9cd76) For creating a tutorial and package for creating a lazy loaded angular library
* [Todd Palmer](https://indepth.dev/creating-a-library-in-angular-6-using-angular-cli-and-ng-packagr/) for a tutorial for creating an angular library
* [PurpleBooth](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2/) for the readme template