Intro

In my last post we reviewed the process of converting some pieces of your Angular CLI application into a package hostable on NPM.

In this post we will discuss a real world example in which I converted one of our own Angular CLI applications into an npm package (@erdiko/ngx-user-admin) and some of the lessons we learned while doing so.

I had some challenges from local development setup, component templates and publishing my package to a namespaced npm organization.

Hopefully we can help you avoid these small pitfalls so you can focus on creating a fantastic package!

Local development & testing with npm link

To start to move code from the Angular CLI application into my new package I had to set my environment up so the Angular CLI application would reference my local code. Honestly, finding an easy way to do this became a giant pain but I think we have found an easy method. I’ll note two methods I used and the side effects of each.

npm i [directory]

The first method I used was installing the local package with each build by providing the full path to my local directory.

Here’s an example of installing the package into your destination project (assuming local package location /home/andy/ngx-user-admin and your destination package is in /home/andy/user-admin):

cd /home/andy/user-admin/app/themes/user-admin
npm i /home/andy/ngx-user-admin

One downside to this method is that you must re-install using this command after each build of your local package. Every. Time.

Clearly this is not ideal and also a productivity time suck.

npm link

The second, and preferred method, is using the npm link command to create a reference to your local code. This method ‘tricks’ npm into installing and referencing your local code instead of the npm registry code.

This method also uses a ‘live’ reference, similar to a symlink, that makes sure your destination or parent package use the most up to date code after you build.

Here’s an example installing the package into your destination project (assuming local package location /home/andy/ngx-user-admin and your destination package is in /home/andy/user-admin):

cd /home/andy/ngx-user-admin
npm link
cd /home/andy/user-admin/app/themes/user-admin
npm link @erdiko/ngx-user-admin

Please note that your linked packages will still be linked after deleting your local node_modules directories. This might cause confusion with later development and testing so be sure to delete all link references when you are done developing with this command:

npm uninstall -g ngx-user-admin

Templates and Bundling

Another difficult challenge I ran into was including an HTML template as a separate file for the components.

When creating a component in an application you can easily reference your HTML templates by a simple path and the compiler includes the files automatically. All of this kind of goes out the window when you attempt to use the AOT Compiler / RollupJS to create a UMD package. Your components now have no idea where the HTML file path is relative to.

I have seen some documentation about using a module ID to reference your module path canonically, but this seems to have been deprecated I eventually settled on reading the HTML into a variable. This method avoided the pitfalls of file paths and I could easily control the HTML I imported.

To achieve this I moved all of the component template files into files with an extension of “.tpl.ts” to make sure they were compiled, and I moved all the HTML into an exported variable to return the code.

Let’s take a closer look at the Home component template file ‘home/home.component.tpl.ts‘:

export const tpl: string= `
<div class="row">
<div class="col-xs-12">
<h1 id="welcome-title">Erdiko User Admin</h1>
</div>
</div>
...

Here is where we actually import and include this template as a variable in `home/home.component.ts`

import { tpl } from './home.component.tpl';
...
@Component({
  selector: 'app-home',
  template: tpl
})
export class HomeComponent implements OnInit {
...

I also used rollup-plugin-angular plugin to validate & minify the inline HTML I import. This allows us to check the HTML before each build as well as remove some whitespace to make this package a little smaller.

From my rollup.config.js file:

plugins: [
angular({
  preprocessors: {
    template: template => minifyHtml(template, htmlminOpts)
  }
}),

While originally VERY frustrating, I think this solution could work in a variety of packages even if you do not choose to bundle your packages up with rollup.

Publishing your package with an organizational namespace

npm’s registry is a great and free tool that allows you to publish your packages for open source software, and they even offer methods to host packages for an organization and even some to prevent public access.

After some research we found it is possible to publish your package under your organization without a paid account, despite the lack of documentation on how to do this.

When publishing your application, use the “–access public” flag.

Here is how we initially published this package:

npm publish --access public

Note: you will only need this flag on your initial publish. Subsequent updates and publishes will not require this flag.

Please note that you must add the organizational namespace to your package.json file before you attempt to publish like this:

{
  "name": "@erdiko/ngx-user-admin",
  "version": "x.x.x",
  ...
}

Documentation and Bug Tracking

Once you publish your package it’s your responsibility to provide good documentation for other developer and end-user documentation.

We plan on creating some end user documentation (coming soon!) using mkdocs since we like it’s themes and it’s ease of use. We also plan including some custom user documentation as we find it’s quite easy to generate attractive HTML from markdown files.

We will use a project called compodocs to create some information about the code itself. This project combs through your typescript code and generates documentation from docblocks. It also creates a handy report noting your comment to code coverage ratio.

It’s also VERY important to provide some channels for your end users to ask questions and report bugs. Since this is an open source project hosted on Github, our general plan is to use the Github Issue tracker to allow user’s to ask questions and report bugs. We believe this is the most straightforward method to interface with our users and to communicate with our development team.

Conclusion

Creating a package can present some significant non-coding challenges and I’m hoping we were able to save you some grief. We’re looking forward to a stable release of this package very soon, and we’re also excited about creating more packages in the future since we now have a major one under our belt.

If you have any questions about this process or about this package, feel free to reach out in the comments or on our github repo!