Managing multiple Angular libraries it’s not a\ntrivial task for a developer or a team. How to structure your\ncode not only shape the future of your codebase but also the\nprocess that you and your team have to define around it.\nMany companies are now looking to follow the big software\ncompanies and using monorepositories. I’ve blogged already on\nthe topic last year\nhere but\nnow that the tooling landscape has\nchanged it is time to revisit my post with a fresher approach.
\nConsidering when Angular 2 first appeared, the tooling, community\nand also general knowledge on how to manage Angular projects\nhas changed a lot. The angular/cli team is doing a great\njob responding to the community needs and including missing\nfeatures to manage multiple projects.
\nA clear example of this is the possibility to generate\nand manage Angular libraries directly through the cli.\nUsing ng-packagr, behind the scene, we can now create and build\nshared libraries between projects in a single repository.
\nAnother good example of how things are changed from was\nwe started, is the great contribution that the NRWL team\nis providing by providing new ways to manage\nnot only Angular applications and libraries, but also\nbackend projects in a single repository.
\nDeciding how to structure the codebase of a project, or\nof an entire company is not an easy task. The number of\nconventions and different process that vary between\nteams can be daunting. Trying to change\nexisting codebases is even more difficult, where we can\nencounter developers friction.
\nThe Angular team doesn’t enforce any specific\npractice managing a monorepository, giving the\nfreedom to the developers to architect around their\ntheir needs. NRWL,\nan open source toolkit to manage monorepository,\non the other hand, is more opinionated.\nThe main idea behind using NX is that all the people\nworking in the monorepo are responsible for keeping\nall the projects and libraries in sync.
\nIn an ideal world all our libraries and projects\nshould be always updated to the latest version,\nbut in reality, each team is working\nagainst a defined backlog and specific stories through the\nsprint. Taking the responsibilities of updating projects\nor libraries across all the teams can and probably will have an\nimpact on the capacity of a team, maybe causing delays to\ndeliver some stories.
\nAnother approach is possible, and we have been following it for the\npast few years in RyanairLabs. We manage a reasonably big\nmonorepository of common components that are shared between\nall the frontend teams. The repository counts more than 30\ndifferent components that vary from\nsimple models shared across applications to more complex\nlibraries to manage the user basket for example.
\nThe common components inside the monorepository, are included\nin various projects in the company, from public facing\nto internal ones. Any team can make changes to the\ncommon components and update them and improve them. There’s\na strict code review process to ensure high code quality\nstandards and all different developer takes turn into\nthe process.
\nTo better understand the components usage, interaction and\nvisual, we are using Storybook\nand we enforce that each library should have at\nleast one story in the storybook to showcase its functionality.
\nAll the actions in the repository, from managing cross dependencies, detecting\nchanges, running multiple commands to publishing are orchestrated by lerna.
\nI will walk you through on how to setup a monorepository\nto manage multiple Angular libraries,\nsimilar to the common components that we\nare using at RyanairLabs. I will use the angular/cli to create the project\nand lerna to deal with the packages.
\nFirst, we need to create an Angular project through\nthe angular/cli:
\nng new angular-monoNow we need to initialise a lerna project.
\nnpx lerna init --independentThe location of the packages and version of the repository are stored\ninto a lerna.json configuration file generated by lerna during the init\nprocess. There are two different modes which lerna\noperate: fixed or independent. A fixed lerna project only\nhas a single version across all of the packages.\nWhile with independent version, each package can be incremented\nindependently without affecting other one’s version. By default,\nlerna uses the fixed mode but we can change our setting by adding\nthe flag —independent during the init command.
\nSince Angular generates libraries into the projects folder,\nwe need to change the standard configuration file in lerna.json\nto point to the correct package folder.
\n{\n \"packages\": [\"projects/*\"],\n \"version\": \"independent\"\n}Next, we can start generating libraries in the project:
\nng generate library first\nng generate library secondThe angular/cli generates the two libraries inside the projects folder\nand creates all the necessary files to test and build the libraries.\nBuilding the libraries require to use the ng build\ncommand passing the name of the library that we want to build.\nNormally we would need to run multiple ng build commands\nto build all our libraries.\nUsing lerna run instead we can invoke a script on every package.\nFirst we need to add the build script on each package.json
\n{\n \"name\": \"first\",\n \"version\": \"0.0.1\",\n \"scripts\": {\n \"build\": \"ng build first\"\n },\n \"peerDependencies\": {\n \"@angular/common\": \"^8.2.4\",\n \"@angular/core\": \"^8.2.4\"\n }\n}After adding the scripts, when running the command npx lerna run build, both the libraries\nare build and the output of our build is in the dist folder.\nRunning commands across all the packages is very handy but it can become a bottleneck. Imagine once the monorepository start growing and,\nthe number of libraries increase, which increases also build and\ntest time. If we are changing only 1 package we shouldn’t have\nto rebuild all the packages at once. By adding filtering option\nto lerna run command we can filter out packages and invoke\nscripts commands only on a subset of packages of our choice:
# run build on all packages that have changed since 'master'\nlerna run build --since master\n\n# run build on all packages that have changed since the last tag\nlerna run build --since $(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1))Part of the publishing process is also bumping the current\npackage version. Determining the next version for a package\ncan be tiresome, especially when you have to remember all\nthe changes that were committed since the past release.\nUsing semantic versioning can help\ngiving a clear indication of the type of changes introduced.\nThe three number format, major, minor and patch gives you\na clear system to calculate the next package version.
\nManually applying semantic versioning in a repository\nit means remembering all the changes committed since the\nprevious release and then mentally determine the version.\nAn automated tool like Commitizen\ncan rescue us from this task. Commitizen\nis a cli tool that generates commit messages following\na standard template, the commit messages then are used\nto calculate the next package version\nand to generate changelogs. To start using commitizen we need\nto initialise our repository
\nnpx commitizen init cz-lerna-changelog --save-dev --save-exact\nnpm i semantic-release --save-devCommitizen is now configured and ready to use.\nOnce we finish our changes\ninstead of using git commit we should always use:
\nnpx git-czCommitizen prompt a set of questions, asking the type of change\nthat you’re committing, scope of the change and more. After we finish\nanswering the questions commitizen creates the commit message based\nupon our answers.\nlerna can now calculate the next package version\nbased upon our commit messages only. Editing the lerna.json\nwe can include conventionalCommits option to the publish\ncommand:
\n{\n \"packages\": [\"projects/*\"],\n \"version\": \"independent\",\n \"command\": {\n \"publish\": {\n \"conventionalCommits\": true\n }\n }\n}Sharing versioned libraries between applications implies compiling them into\nthe Angular package format and publish them to an npm registry. We have discussed\nalready how to build Angular libraries now we can focus on how to publish them.
\nThe command responsible for publishing packages in lerna is called lerna publish.\nThe command goes through a series of steps and takes care of the full publishing\nprocess. It first creates a new release increasing the version of the packages\nchanged since the last one. Then generates the version\ntags and lastly, it publish the packages to the npm registry.
\nPublish operates in each package folder but angular/cli build output for libraries\nis in the root folder. We need to change the destination folder so that\nlerna publish can easily find the libraries to publish.\nThe destination folder for the libraries is specified\nthe ng-package.json file and we have to modify the dest folder:
\n{\n \"$schema\": \"../../node_modules/ng-packagr/ng-package.schema.json\",\n \"dest\": \"dist\",\n \"lib\": {\n \"entryFile\": \"src/public-api.ts\"\n }\n}To avoid committing build files we can add this line to .gitignore:
\n**/dist/The last step now is to include some scripts that hooks\ninto the lifecycle of lerna commands.
\nUsing a prepublish script in the root package.json we can trigger the build\nfor all the changed packages. This ensure that the packages built have\nthe correct version in their respective package.json
\n{\n ...\n \"prepublish\": \"lerna run build --since HEAD~1 --concurrency=1\"\n ...\n}We are building here only the packages that changed since the last commit, that’s\nvery useful especially in CI/CD environments if you want to build and publish on each\ncommit incoming. You can modify the —since to your needs following lerna\nfilter options.
\nUsing the flag —concurrency=1 ensure that the packages are correctly built\nwith ngc and respecting the topology.
\nThe script postpublish runs\nafter the lerna publish command and is useful\nto clean up the library folder after we have published the liraries.\nWe need to include the script in each library package.json:
\n{\n \"name\": \"first\",\n \"version\": \"0.1.0\",\n \"scripts\": {\n \"build\": \"ng build first\",\n \"postpublish\": \"rm -rf dist/\"\n },\n \"peerDependencies\": {\n \"@angular/common\": \"^8.2.4\",\n \"@angular/core\": \"^8.2.4\"\n }\n}Now that we completed all the steps we can build and publish\nour libraries:
\nnpx lerna run build\nnpx lerna publish --contents distThe libraries are all published and ready to be imported into\nour applications. Thanks to conventional-changelog-angular\neach package contains a changelog file with all the commits\nof a version divided by commit type.
\nAngular provides a comprehensive framework for managing frontend applications\nmaking a lot of decisions for us. A codebase, on the other hand, should be\ntailored to our development needs. Using lerna with the correct tools we can\nreduce the pain when managing packages and versions.
\nI’ve left a github repository preconfigured with all the\nsteps of the article\nhttps://github.com/izifortune/angular-mono to explore.
\nUpdate 09/10/19:
\nWorking with multiple libraries in a monorepository will eventually\nrequire to use and import a library inside another one. If you are following DRY\nprinciples you want to reuse a service or a component when and where its needed.\nUsing npm within a lerna monorepository has some limitation that we need to be\naware. When you have two linked libraries ng-packagr will not recognise the\nlinked library at build time. Another limitation will be once you start making changes to both of\nchanges to two different libraries at the same time, breaking contracts between\nthem.
\nIn general npm is missing the ability to link together the local libraries\nwhile working on a monorepository. Yarn on the other hand, has a feature\nthat covers exactly our needs: workspaces.
\nLet’s switch to from npm to yarn in our repo making sure to delete the\npackage-lock.json which yarn will replace with yarn.lock. We can also\nspecify to lerna what package manager to use and inform that we will use\nworkspaces inside lerna.json
\n...\n \"packages\": [\n \"projects/*\"\n ],\n \"npmClient\": \"yarn\",\n \"useWorkspaces\": true,\n...We need to locate the workspaces in the project by adding to the package.json:
\n \"workspaces\": [\"projects/*\"]Our libraries will be located in a different folder structure that the one\ndefined by the angular/cli we have to change the mapping declartion paths\ninside our tsconfig.json
\n...\n\"paths\": {\n \"first\": [\n \"projects/first/dist\"\n ],\n \"first/*\": [\n \"projects/first/dist/*\"\n ],\n \"second\": [\n \"projects/second/dist\"\n ],\n \"second/*\": [\n \"projects/second/dist/*\"\n ],\n}As a general rule of thumb we always specify imported libraries as\npeerDependencies. This ensure that we are not including the same\nlibrary multiple times on an application, leaving the latter to\nadd all the libraries as dependencies.
\nNow that the libraries are linked we need to ensure that the\ncommands order is respected. If we are building library second which\ndepends on library first in the monorepository we need to have\nfirst built so that we can consume it. The command lerna run respect the topological libraries sorting\nbut it won’t work with peerDependencies. We have to switch then\nto devDependencies so that lerna can understand that correct\norder of execution.
\n \"devDependencies\": {\n \"first\": \"*\"\n }I added a third library on the example repository linked to demonstrate how\nthe linking will work here
\n** Update 29/01/21 **
\nWhen working linking locally the packages in the monorepo in another Angular application\nremember to add the flag preserveSymlinks: true in both tsconfig.json\nand angular.json as follows:
\n// tsconfig.json\n\"compilerOptions\": {\n \"preserveSymlinks\": true// angular.json\n \"projects\": {\n ...\n \"architect\": {\n \"build\": {\n ...\n \"options\": {\n \"preserveSymlinks\": true,\n ...