Angular library with demo project

Angular, with the help of angular-cli makes it easy to create a library project. But when your library is about components, it's very useful to have a visual rendering of what you're creating, and not only the lib code and tests.
In this article, we'll see how we can easily create in a same project, the library and the demo app, but still keep a coherent structure like we need for a library project.

Generate the Angular workspace

Like for every Angular project, the first step is to generate the workspace for your library:

ng new my-lib --createApplication=false # for Angular < 16
ng new my-lib --no-create-application # for Angular 16+

⚠ Don't forget the createApplication option so that you don't generate the skeleton of an app inside of your workspace. We will see later how to organize the project structure.

Now you should see the base Angular workspace, with a project folder to correctly structurate libraries and demo app.

Generate the library in the project

Angular-cli can generate the library project scaffolding for you with the command

ng generate library myLib

You should now have a my-lib folder inside projects and that's where you will place all components related to the library you're creating.

If you open the ./tsconfig.json file, you should also see the path property that was created with the information about your library. This will be useful later to easily import it from the demo app.

In ./tsconfig.json

    "paths": {
      "my-lib": [
        "dist/my-lib/my-lib",
        "dist/my-lib"
      ]
    },

Generate the demo app

To generate the demo app, Angular-cli again provide you a command for scaffolding generation.

ng generate application demo

As you noticed, this time, we don't use the library keyword, but the application one. The generated project will be different as it can be "started" to be debugged in the browser.

The difference of using generate application command, instead of doing this at the first step with ng new my-lib, is that it allows a workspace name different from the initial app name, and ensures that all applications reside in the /projects subfolder, matching the structure of the configuration file.

More info in the angular-cli documentation.

Import the lib in the demo project

Now that you've created the components you wanted in the lib and also the demo project to see your component in the browser, what you're missing is the glue between both.
This link is done by importing your library module into the demo project. As we have seen, the tsconfig was automatically updated with the new path, so now in your project, you just need to specify the import with the path key, like:

In demo/src/app/app.module.ts

import { MyLibModule } from 'my-lib';

That way, when the build is started, it will detect the my-lib path, and with the help of the config, it will know where to look for to import the module correctly.

Don't forget to build

One last thing to consider, is that in this tsconfig.json file, the path is looking for the dist folder. But this one doesn't exist yet. This mean that if you want your demo project to find your library components, you will need to build the library first.

For that purpose, you can add a script in the package.json file to easily build the lib every time you need it to be updated.

In package.json

  "scripts": {
    "build-lib": "ng build my-lib --watch",
    ...
  }

And then simply build the lib with

npm run build-lib

🧐 If this article helped you in a way, don't hesitate to share it or comment 💬

Credits

Cover image by @laukev