Building an Angular Library for npm and for Local Use

For our current project, my software team is building an Angular library that can be used in a few different applications. We’re creating these components in a separate project and using Storybook to test our components and gain confidence that they work correctly before being used in other applications.

We’re deploying this library to npm for use in the other projects that use these components. But, we also want to be able to import the components locally to test them without having to re-deploy to npm for every little check.

Building for npm

Our component library project is laid as follows, excluding extraneous files and folders:

├── package.json
├── projects
│   └── components
│       ├── package.json
│       └── src
│           ├── lib
│           │   ├── component-A
│           │   │   └── ...
│           │   ├── component-B
│           │   │   └── ...
│           │   └── component-C
│           │       └── ...
│           └── public-api.ts
└── stories
    ├── Component-A.stories.ts
    ├── Component-B.stories.ts
    └── Component-C.stories.ts

Our component library exists in the projects/components directory. The public-api.ts file contains exports for every module and component exposed by the library.

Deploying a new version of the component library to npm is accomplished by running an npm run publish script which we have set up in the root package.json. (Note that each command is on its own line for ease of readability. In an actual package.json, this should all be one long line.)

"publish": "npm install && 
  cd projects/components && 
  npm version patch && 
  cd ../.. &&
  npm run build &&
  git commit -m bump projects/components/package.json && 
  cd dist/components && 
  npm publish"

This increments the patch version of the component library, builds the library, commits the new version, and publishes the component library to npm in one easy command. It also ensures that it happens correctly every time.

Building to Run Locally

What if you want to test a component in another project without pushing to npm? Often answers to, “How do I install a module locally with npm?” just tell you to run npm install /path. This should work if you’re writing plain JavaScript but won’t for our components which are written in TypeScript. We found that building and packaging the code allows us to then import it locally using these commands in the component library root run:

npm run build
cd dist/components
npm pack

This builds and packages your code into a compressed file named using the name and version from your package.json, e.g: ui-library-0.0.1.tgz. Then you can navigate to the project you want to use the components in and run:

npm install /path/to/dist/ui-library-0.0.1.tgz

This will create an entry in your package.json which should be similar to:

"dependencies": {
    "ui-library": "file:/path/to/dist/ui-library-0.0.1.tgz",
  },

Angular Library Complete

You can now see your components running in another local application! This will help you test that both your components are working correctly in other environments and that your other project isn’t breaking your component. That’s great since both of these can happen frequently when building complex components in a separate project.