Building an Angular Library
Run yarn
to install dependencies.
Run npm start
to start development server.
This is my coursework for Angular University's "Angular Advanced Library Laboratory: Build Your Own Library" course.
Branches au-input : First Section of the Course 1-create-lib 2-content-projection 3-mimic-default-behaviour 4-design-component-styling 5-setup-for-distribution 6-testing
Steps
First, design the public API for the library.
-
START MAKING LIB
-
Make a
lib
folder for public components. -
Design component API with
@Input()
. -
[ngClass] works great with a getter method
-
Style components. Angular gives us good (but not perfect) style encapsulation
-
use
:host
-
CONTENT PROEJCTION
-
Zoom in and out to see how well the structural styles hold up.
-
AVOID wrapping regular HTML attributes by using Content Projection.
-
If using content projection, you'll need to override the styles of the projected element
-
If you need to break style encapsulation use
:host ::ng-deep <component>
-
MIMIC DEFAULT BEHAVIOUR
-
You could use
template references
and@ContentChild()
to get a reference to the element being passed in to the component -
However, that's not usually what you will want to do. Instead, make a directive that selects any html element that you are looking for, and pass that directive to @ContentChild()
-
In Angular, it is often practical to not reference projected content directly.
-
Add a helpful error message with
ngAfterContentInit
to make sure the component is loaded correctly. -
Use
@HostBinding
to implement state classes for projected content -
DESIGN COMPONENT STYLING
-
Separate Structural styles from Theme styles
-
:host-context()
selects by working with class names defined outside the component. It is very useful for providing extra themes in our library. -
Angular has style isolation mechanisms that work differently from regular CSS.
-
The default Angular style isolation mechanism, Emulated View Encapsulation, is design to give us good assurance than our styles will be encapsulated when used in other projects
-
Most of the time we will want to use Emulated View Encapsulation
-
SETUP FOR DISTRIBUTION
-
Make sure AoT Compilation is on.
-
Make a module file that has the same name as the npm package you will create.
-
Add to package.json
"serve:prod": "ng serve --prod --aot"
, -
Setup an
index.ts
at the root of application and export the new module. -
TESTING
-
This is a scenario where we need to do an INTEGRATION test because our component will be integrating into other people's code.
-
Start by giving your component pieces unique ids
-
Add a test class to content that is being projected so that its existance can be tested
-
Setup an app level test by configuring the testing module to have AppComponent AuFaInputComponent and InputRefDirective.
-
Write some tests
-
For integrated tests you may need to run Angular Change Detection to ensure that your expectations are working with elements that have been fully processed
-
fixture
is a very helpful class that has all kinds of useful debugging features like.debugElement
.nativeElement
-
There is a
By.css
helper to select pieces from the component under test. -
PUBLISH TO NPM
-
Using the npm package format is the most recommended for open-source. However, if you want to keep the library private it's actually simpler to publish.