Publishing Angular Libraries to npm.

Publishing Angular Libraries to npm: From Zero to Hero (and Maybe a Little Bit of Villain)

Alright class, settle down, settle down! Today, we’re diving into the exciting, sometimes frustrating, but ultimately rewarding world of publishing Angular libraries to npm. Think of it as crafting your own superhero utility belt of reusable components, services, and modules, ready to be deployed to save countless developers from the drudgery of reinventing the wheel. 🦸‍♀️

This isn’t just about slapping some code on npm and hoping for the best. We’re talking about architecting, building, testing, and packaging your library like a seasoned professional. We’ll cover everything from project setup to versioning strategies, all while injecting a healthy dose of humor to keep things from getting too…well, angular. 😜

Why Bother Publishing Libraries Anyway?

Before we get our hands dirty, let’s address the elephant in the room: why should you bother publishing an Angular library?

Code Reusability: This is the big one. Avoid writing the same code over and over again. Think of it as the ultimate copy-paste prevention mechanism. 🚫✂️
Sharing is Caring: Contribute back to the Angular community. Share your brilliance and help others build amazing applications faster. ❤️
Centralized Updates: Fix a bug in one place and the fix propagates to all applications using your library. It’s like magic, but with more coding. ✨
Maintainability: Easier to maintain and update a single, well-defined library than scattered code snippets across multiple projects. Think of it as Marie Kondo-ing your codebase. 🧹
Learn and Grow: Building and publishing a library forces you to think about your code in a different way, improving your overall coding skills. It’s like a workout for your brain! 💪

Our Curriculum for the Day:

Here’s what we’ll be covering:

Setting up the Stage: Project Initialization 🎭
Crafting the Masterpiece: Building Your Library 🎨
Testing, Testing, 1, 2, 3: Ensuring Quality ✅
Packaging Power: Building for Distribution 📦
npm Ninja: Publishing and Versioning 🥷
Documentation Dojo: Writing Excellent Docs 📖
The Afterparty: Maintenance and Updates 🎉

1. Setting Up the Stage: Project Initialization 🎭

First, we need a clean slate. We’ll use the Angular CLI to create a new workspace and a library within that workspace. Fire up your terminal and let’s get started:

ng new my-workspace --create-application false
cd my-workspace
ng generate library my-awesome-library

ng new my-workspace --create-application false: This creates a new Angular workspace named my-workspace without generating a default application. We only want the library.
cd my-workspace: Navigates into the newly created workspace.
ng generate library my-awesome-library: This generates a new Angular library named my-awesome-library within the workspace.

Key Files and Folders:

Let’s peek inside our newly created library:

File/Folder	Description
`projects/my-awesome-library`	This is where your library’s source code lives. You’ll find components, services, modules, and everything else that makes your library tick.
`projects/my-awesome-library/src`	The heart of your library! This folder contains the `public_api.ts` file, which defines the public interface of your library. Anything you want consumers to use needs to be exported here.
`projects/my-awesome-library/ng-package.json`	This file configures how your library is packaged. It specifies the entry point, assets to include, and other important settings. Think of it as the recipe for turning your code into a distributable package.
`tsconfig.json`	TypeScript configuration file for the entire workspace.
`tsconfig.lib.json`	TypeScript configuration file specifically for your library. This allows you to tailor the compilation process for your library independently from the rest of the workspace.
`package.json`	Contains metadata about your workspace, including dependencies, scripts, and version information. This is not the `package.json` that will be published to npm. That one will be generated in the `dist` folder when you build the library.

Important Note: Your library’s code lives in projects/my-awesome-library/src, not in the root src directory. Don’t make that mistake! You’ll be chasing your tail like a dog with a frisbee if you do. 🐕‍🦺

2. Crafting the Masterpiece: Building Your Library 🎨

Now, let’s add some functionality to our library. For simplicity, let’s create a simple "Hello World" component.

First, generate the component:

ng generate component hello-world --project my-awesome-library

This will create a hello-world component within the projects/my-awesome-library/src/lib directory.

Now, let’s modify the component’s code:

projects/my-awesome-library/src/lib/hello-world/hello-world.component.ts:

import { Component, OnInit, Input } from '@angular/core';

@Component({
  selector: 'lib-hello-world',
  template: `
    <p>
      Hello, {{ name }} from My Awesome Library!
    </p>
  `,
  styles: [
  ]
})
export class HelloWorldComponent implements OnInit {

  @Input() name: string = 'World';

  constructor() { }

  ngOnInit(): void {
  }

}

We’ve added an @Input() property called name so users can customize the greeting.

Next, we need to export our component from our library’s module and public_api.ts.

projects/my-awesome-library/src/lib/my-awesome-library.module.ts:

import { NgModule } from '@angular/core';
import { HelloWorldComponent } from './hello-world/hello-world.component';

@NgModule({
  declarations: [
    HelloWorldComponent
  ],
  imports: [
  ],
  exports: [
    HelloWorldComponent // Export the component!
  ]
})
export class MyAwesomeLibraryModule { }

projects/my-awesome-library/src/public_api.ts:

/*
 * Public API Surface of my-awesome-library
 */

export * from './lib/my-awesome-library.service';
export * from './lib/my-awesome-library.component';
export * from './lib/my-awesome-library.module';
export * from './lib/hello-world/hello-world.component'; // Export the component!

Crucial Point: Anything you don’t export from public_api.ts is considered private to your library. Users won’t be able to import it, even if they try. This is a good thing! It allows you to refactor your internal code without breaking existing consumers of your library. 🔒

3. Testing, Testing, 1, 2, 3: Ensuring Quality ✅

Before unleashing your library upon the world, you need to make sure it works! Angular libraries come with built-in testing support using Karma and Jasmine.

Let’s write a simple test for our HelloWorldComponent:

projects/my-awesome-library/src/lib/hello-world/hello-world.component.spec.ts:

import { ComponentFixture, TestBed } from '@angular/core/testing';

import { HelloWorldComponent } from './hello-world.component';

describe('HelloWorldComponent', () => {
  let component: HelloWorldComponent;
  let fixture: ComponentFixture<HelloWorldComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [ HelloWorldComponent ]
    })
    .compileComponents();
  });

  beforeEach(() => {
    fixture = TestBed.createComponent(HelloWorldComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  it('should display "Hello, World from My Awesome Library!" by default', () => {
    const compiled = fixture.nativeElement;
    expect(compiled.querySelector('p').textContent).toContain('Hello, World from My Awesome Library!');
  });

  it('should display "Hello, John from My Awesome Library!" when name is John', () => {
      component.name = "John";
      fixture.detectChanges();
      const compiled = fixture.nativeElement;
      expect(compiled.querySelector('p').textContent).toContain('Hello, John from My Awesome Library!');
  });
});

To run the tests, use the following command:

ng test my-awesome-library

This will launch a browser window and run the tests. Make sure all your tests pass before proceeding. If they don’t, fix them! No one wants a buggy library. 🐛

Testing Best Practices:

Write unit tests for all your components, services, and pipes.
Use mock data to isolate your tests.
Aim for high test coverage. (80% or higher is a good goal)
Consider using end-to-end testing frameworks like Cypress or Protractor for more complex scenarios.

4. Packaging Power: Building for Distribution 📦

Now, it’s time to package our library for distribution. This involves compiling the TypeScript code, creating a distributable package, and generating the necessary metadata.

To build the library, use the following command:

ng build my-awesome-library

This will create a dist/my-awesome-library directory containing the compiled code, typings files, and a package.json file.

Inside the dist Folder:

Let’s take a look at what’s inside the dist/my-awesome-library folder:

bundles/: Contains the UMD bundles of your library.
esm2015/ and esm5/: Contains the ECMAScript module versions of your library.
fesm2015/ and fesm5/: Contains the Flat ECMAScript module versions of your library.
lib/: Contains the compiled JavaScript code.
my-awesome-library.d.ts: Contains the TypeScript declaration file.
package.json: A crucial file that describes your library to npm. This is the package.json that will be published.

Understanding package.json (The Distributable Version):

The package.json file in the dist folder is different from the one in your workspace root. It’s specifically tailored for npm and contains information about your library, such as its name, version, description, keywords, and dependencies. Make sure to review and customize this file before publishing.

Here’s an example:

{
  "name": "my-awesome-library",
  "version": "0.0.1",
  "description": "An awesome Angular library that says hello!",
  "main": "bundles/my-awesome-library.umd.js",
  "module": "fesm2015/my-awesome-library.js",
  "es2015": "fesm2015/my-awesome-library.js",
  "esm5": "fesm5/my-awesome-library.js",
  "fesm2015": "fesm2015/my-awesome-library.js",
  "fesm5": "fesm5/my-awesome-library.js",
  "typings": "my-awesome-library.d.ts",
  "scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  },
  "author": "Your Name",
  "license": "MIT",
  "peerDependencies": {
    "@angular/common": "^12.0.0",
    "@angular/core": "^12.0.0"
  }
}

Key package.json Properties:

name: The name of your library on npm. Choose wisely! 🧠
version: The current version of your library. Follow semantic versioning (more on this later).
description: A brief description of your library. Make it compelling! ✨
main: The entry point for CommonJS environments (like Node.js).
module: The entry point for ES module-aware bundlers (like Webpack).
typings: The path to your TypeScript declaration file.
peerDependencies: Dependencies that your library expects the consuming application to have. This is important for avoiding version conflicts. For example, you’ll likely want to list @angular/core and @angular/common as peer dependencies.

Important Note about Peer Dependencies: Be very careful about specifying peer dependencies. If a consuming application doesn’t have the exact version specified in your peerDependencies, npm will issue a warning (though it will still install the library). This can lead to runtime errors if your library relies on specific features of a particular version of a peer dependency.

5. npm Ninja: Publishing and Versioning 🥷

Now for the moment of truth! Let’s publish our library to npm.

Before you publish:

Create an npm account: If you don’t already have one, sign up at npmjs.com.
Log in to npm: In your terminal, run npm login and enter your credentials.
Navigate to the dist folder: cd dist/my-awesome-library

Publishing the Library:

Finally, run the following command:

npm publish --access public

npm publish: This command publishes your library to npm.
--access public: This makes your library publicly available. If you omit this, your library will be published as a private package (which is only accessible to you or your organization).

Congratulations! Your library is now live on npm! 🎉

Versioning: The Semantic Versioning Samurai

Versioning is crucial for managing updates and ensuring compatibility. We follow Semantic Versioning (SemVer), which uses a three-part version number: MAJOR.MINOR.PATCH.

MAJOR: Incompatible API changes. A major version bump indicates that existing code using your library will likely break. Use this when you’ve made significant changes that require users to update their code.
MINOR: New features added in a backwards-compatible manner. A minor version bump indicates that new functionality has been added, but existing code should continue to work without modification.
PATCH: Bug fixes and minor improvements that are backwards-compatible. A patch version bump indicates that you’ve fixed a bug or made a small improvement without introducing any breaking changes.

npm Version Commands:

npm provides handy commands for managing versions:

npm version patch: Increments the patch version (e.g., 1.0.0 becomes 1.0.1).
npm version minor: Increments the minor version (e.g., 1.0.0 becomes 1.1.0).
npm version major: Increments the major version (e.g., 1.0.0 becomes 2.0.0).

Versioning Workflow:

Make your changes.
Test your changes thoroughly.
Determine the appropriate version bump based on the SemVer guidelines.
Run npm version <patch|minor|major> to update the version number in package.json.
Build your library (ng build my-awesome-library).
Navigate to the dist folder (cd dist/my-awesome-library).
Publish your library (npm publish --access public).
Tag your commit with the version number (e.g., git tag v1.0.1).
Push your tags to your remote repository (e.g., git push origin --tags).

6. Documentation Dojo: Writing Excellent Docs 📖

Your library is only as good as its documentation. Clear, concise, and comprehensive documentation is essential for attracting users and ensuring they can easily use your library.

Documentation Best Practices:

README.md: This is the first thing users will see on npm. Make it informative and engaging. Include:
- A brief description of your library.
- Installation instructions.
- Basic usage examples.
- Links to more detailed documentation (if applicable).
- Contribution guidelines.
- License information.
API Documentation: Generate API documentation using tools like Compodoc. This provides detailed information about each component, service, and module in your library.
Examples: Provide clear and concise examples of how to use your library in different scenarios.
Live Demo: Consider creating a live demo of your library using StackBlitz or CodeSandbox. This allows users to quickly see your library in action.
Keep it Updated: Regularly update your documentation to reflect any changes in your library.

Example README.md:

# My Awesome Library

An awesome Angular library that says hello!

## Installation

```bash
npm install my-awesome-library

Usage

import { MyAwesomeLibraryModule } from 'my-awesome-library';

@NgModule({
  imports: [
    MyAwesomeLibraryModule
  ]
})
export class AppModule { }

<lib-hello-world name="John"></lib-hello-world>

API Documentation

[Link to Compodoc documentation]

Contributing

See CONTRIBUTING.md for details on how to contribute.

License

MIT


### 7. The Afterparty: Maintenance and Updates 🎉

Publishing your library is not the end; it's just the beginning! You need to maintain your library, address bug reports, and add new features.

**Maintenance Best Practices:**

*   **Monitor bug reports and feature requests.**
*   **Respond to user questions and issues promptly.**
*   **Regularly update your dependencies.**
*   **Follow semantic versioning when releasing updates.**
*   **Write clear and concise release notes.**

**Updating Your Library:**

When you need to update your library:

1.  **Make your changes.**
2.  **Test your changes thoroughly.**
3.  **Determine the appropriate version bump based on the SemVer guidelines.**
4.  **Run `npm version <patch|minor|major>` to update the version number.**
5.  **Build your library (`ng build my-awesome-library`).**
6.  **Navigate to the `dist` folder (`cd dist/my-awesome-library`).**
7.  **Publish your library (`npm publish --access public`).**
8.  **Tag your commit with the version number.**
9.  **Push your tags to your remote repository.**

**Deprecation:**

If you need to deprecate a feature or an entire library, use the `npm deprecate` command:

```bash
npm deprecate my-awesome-library@"<version range>" "<deprecation message>"

For example:

npm deprecate my-awesome-library@"<1.0.0" "This version is deprecated. Please upgrade to 1.0.0 or later."

This will display a warning message to users who try to install the deprecated version.

Conclusion: From Zero to Library Hero!

Congratulations, you’ve made it! You’re now equipped with the knowledge and skills to publish your own Angular libraries to npm. Remember, it’s a journey of continuous learning and improvement. Don’t be afraid to experiment, ask questions, and contribute back to the Angular community. Now go forth and build something awesome! 🚀

(Class dismissed!)