DEV Community: Alain Boudard

[Boost]

Alain Boudard — Thu, 22 May 2025 12:46:12 +0000

Marko Stanimirović for NgRx

May 12 '25

Announcing Events Plugin for NgRx SignalStore: A Modern Take on Flux Architecture

#ngrx #angular

Comments 11

6 min read

Adding scss assets to Angular library

Alain Boudard — Thu, 30 Nov 2023 15:10:22 +0000

In a previous article, I was talking about some ways to include assets in an Agular library. Let’s go a little further, and see how we can handle scss files and compile in the application and not in the library.

The example of bootstrap

One example we can name is how we can integrate bootstrap style to our application. It goes like this :

Install bootstrap
Reference bootstrap scss in angular.json or global styles.scss
Eventually override some variables of the library

Note: if you import such a scss file like bootstrap, you may override some variables, only if you import the stylesheet in your styles.scss (or another one) of your project. It won’t work from angular.json.

The goal of our application

The main goal here is to have an Angular application that doesn’t require the library scss to be previously built. We will see what options we have to let the application do the job. The library will not only expose scss files but also images and fonts.

This means that our library will not expose compiled css to the outer world, but sometimes, and it can be convenient, a library can expose both the scss and the css.

Of course that means that each time our application will build, this task will be running, but as we might already know, Angular build system does separate typescript and style build.

The Angular workspace

Let’s create a workspace with both a library and an application.



ng new ng-assets-wk --create-application false
cd ng-assets-wk
ng g library @abo/ng-lib
ng g application ng-app -routing --style scss

We can write some scripts to build both library and application :



"build:lib": "ng build --project @abo/ng-lib",
"watch:lib": "ng build --watch --configuration development --project @abo/ng-lib",
"build:app": "ng build --project ng-app",
"watch:app": "ng build --watch --configuration development --project ng-app",

Styles in the application

In the src/styles.scss file, we can add some basic style and reference a simple asset with variables.

When we compile the application in watch mode, we see that chunks are produced, both js and css files.

What can seem weird, is that when you modify your scss files (main file or variables), the message is pretty simple and doesn’t reflect the fact that styles.css output has indeed been updated.

Let’s note that there is a difference in the build output when you alter any of the source code, like a component, wether it’s typescript, html template or scss file, which are not processed like the stylesheets referenced in angular.json configuration file in the styles section :

This makes sense because Angular uses a default configuration for style isolation which is encapsulation: ViewEncapsulation.Emulated that would prevent styles declared for a component to spread to other components.

Styles in the library

Ok, now we want to add scss files to our library, and expose them to our application. Let’s create an assets folder in the libray and put some files in it:

Note: if you want to be able to override your scss variables, you would need to use the keyword !default like here, in the first declaration of your variable.

Let’s add this folder, and all files in it, to the ng-package.json file of the library. You can find more information here about why we should declare this assets property.



  "assets": [
    "./assets/**/*.*"
  ]

During the build of the library, the folder should be exported in the dist folder. Following a previous article about Angular libraries, we will publish on a local Verdaccio server. Now we can add the scss file to the list of styles of our application in the angular.json (the point is to be as close as a production ready use case).



"unpublish:lib": "npm unpublish @abo/ng-lib --registry http://localhost:4873/ --force",
"publish:lib": "ng build @abo/ng-lib && cd dist/abo/ng-lib && npm publish --registry http://localhost:4873/",
"install:lib": "npm install @abo/ng-lib --registry http://localhost:4873/",

Don’t forget to remove the reference to the library path in the tsconfig.json file.

Note: if you build your application in production mode, you might see something weird in the code inspector : the styles appear twice :

This is due to an implicit configuration in production build mode called inlineCritical (turn this to false to disable if you want) that is meant to reduce the initial styled render of the page :



"optimization": {
  "styles": {
    "minify": true,
    "inlineCritical": true
  }
}

Anyway, if we run our application, the style of the library should be compiled with our application and be applied. Since we want to override the variables, let’s try to use this stylesheet in our main styles.scss file.

We remove the reference in the angular.json file. Then we add a reference in the styles.scss file :

This is working, obviously, but it doesn’t look great DX wise, so we will use the export property of the Angular package format, in order to declare how we can access our scss resources. In this Angular documentation, it states that you need to declare this exports property. As a result, we can use the entrypoint of the library in the scss import statement.

This import is way much cleaner right ?

Add other files to the scss package

Now, let’s add the most used files in combination with css: fonts and images.

In our library assets folder, we can add an /img folder with images, here we add two logos of Angular, and then we can simply reference these images in any CSS rule that we see fit.

Now we should be able to see our images in the page with some simple code :



<h1 class="logo next">Angular next</h1>
<h1 class="logo">Angular</h1>

Now let’s add a custom font of our choice. Let’s go with Segoe UI font. In our library assets folder, we can add an /fonts folder with the desired files. For the sake or readability, let’s create a dedicated _fonts.scss file and reference it in our main library scss file.

In our main scss files, we import the fonts definition, and use the font in the body for a start, but anywhere you would want :

Now we can test in the browser if everything is ok, the font should be loaded in the devtools.

Use the library scss in application components

We saw that the components scss are not processed like the main styles declared from angular.json section. But we still can use our declared variables (or any kind of tool, like mixin for example) in our components.

Without any modification we could use the @use annotation and consume our variables like that :



@use "node_modules/@abo/ng-lib/assets/lib-variables" as lib;

But again, that’s not very nice, we can then add another entry in our library package.json and have a better import in our component’s scss :

With the same pattern, we can declare a mixins file and use it through an export entry :

Conclusion

We saw that having a clean Angular library exposing scss resources is quite easy to configure. The main advantage of this method is to get rid of the css pre-build task in the library, and the maintainability of our custom variables and other uses of scss files. This is possible thanks to the scss capabilities of the Angular build, since we never had to launch a dedicated sass build.

The use of the Angular endpoint reference is a plus for any library publisher.

References

https://github.com/aboudard/ng-assets-wrk

https://github.com/ng-packagr/ng-packagr/blob/main/docs/copy-assets.md

Using Angular cache with library

Alain Boudard — Tue, 05 Sep 2023 07:40:00 +0000

How the angular cache can interfere with the build of an application.

I was reading this nice article about Angular cache (starting with version 13), and it reminded me that I stumbled upon an issue with this feature regarding the development of libraries. Basically, if you install a library with npm, if the source code of the library changes but not the version number, what happens.

The project

The Angular project we will be using consists of a workspace in which there will be a library and an application. Normally, when we develop an Angular library in the same workspace than the application, the local tsconfig file takes care of telling Angular where the source code is so that we don’t need to install the library.

For this project, we won’t be using the library directly, but we will publish it to any kind of registry compatible with npm and install it with npm install command.

I had 2 tools available :

A free demo account with jfrog.io that allows you to host your Artifactory registry in the cloud. You get a domain name like https://username.jfrog.io and can publish right away.
A local install of Verdaccio running next to our app.

The first option is really nice to test, but it’s limited in time, and our actual needs for this demo are very simple and Verdaccio is more than enough.

The local npm registry

Using verdaccio is very simple :

Install the package globally :

npm install -g verdaccio

Run verdaccio

verdaccio

You should see the server running :

And access your empty registry (note these commands for using this registry for later) :

The Angular workspace

Let’s create a very simple angular workspace and add a library and an application.

ng new ng-lib --create-application false
ng g application testapp
ng g library @abo/testlib

This way we have both projects in the workspace. Let’s remove the path configuration from the tsconfig file :

This way, we will only use the library through the npm install, using our Verdaccio registry.

Note : I’m aware that using an Angular library this way is not the proper way when you’re in dev mode but this is not the point here.

Publish our library with npm

We must have followed the Verdaccio instructions to create the user we will login with. Then we can actually login, build the library and publish it :

npm login - registry http://localhost:4873/
Username: admin
Password:
Email: (this IS public) abo@abo.com
Logged in as admin on http://localhost:4873/.*

Building and publishing the angular library with the publish:lib script :

"scripts": {
    "ng": "ng",
    "start:app": "ng serve testapp",
    "build:app": "ng build testapp",
    "build:lib": "ng build @abo/testlib",
    "publish:lib": "ng build @abo/testlib && cd dist/abo/testlib && npm publish --registry http://localhost:4873/",
    "watch": "ng build --watch --configuration development",
    "test": "ng test"
  },

The result must look like that :

And in our Verdaccio console, we should see the library added to the registry :

Add the library to the application

This is pretty easy, let’s clean up the code of the placeholder Angular application, install our library via the registry and add the single component exposed to our home page.

npm i @abo/testlib --registry http://localhost:4873/
...
+ @abo/testlib@0.0.1
added 1 package, removed 1 package and audited 992 packages in 8.988s

Be careful when adding your library because some IDEs have an auto-import feature that is a little bit too fast to find the proper import. You could have something like that (and this would trigger application recompile when unwanted) :

import { TestlibModule } from "../../../abo/testlib/src/lib/testlib.module";

When you would only want this :

import { TestlibModule } from "@abo/testlib";

Let’s alter the library and publish a new version to see the changes. I don’t use any automatic semantic versioning system, let’s use simply the npm version command to upgrade the library and then re publish.

"scripts": {
    "upgrade-version:lib": "cd projects/abo/testlib && npm version patch",
    "publish:lib": "ng build @abo/testlib && cd dist/abo/testlib && npm publish --registry http://localhost:4873/",

Check that your library is up to date in Verdaccio and re install in your Angular workspace (the new 0.0.2 version).

npm i @abo/testlib@0.0.2 --registry http://localhost:4873/

The application should show the new library version :

Publish the same version of Angular library

Now, why would we want to publish the same version ? This could be a typical use case when you want to strictly control a release version, maybe aligned with a Maven package or something else. Anyway, let’s see what happens.

If you alter your code in the library and simply try to re publish it, you will get an error like this :

Most of the npm registries prevent from publishing the same version, some allow you to set options to override, but I didn’t find the option in verdaccio — if anyone knows about it, feel free to say it in the comments.

Anyway, we will simply unpublish the npm package and re publish it.

"scripts": {
    "unpublish:lib": "npm unpublish @abo/testlib --registry http://localhost:4873/ --force",

So the tasks here are :

Alter the library component
Unpublish the library on Verdaccio
Re build et re publish the library
Uninstall / re install the library in our Angular workspace
Run the application and see the result

Well, there is no difference, the application was built with a previous verison of the library. Yet, when we take a look at the package-lock.json we see that even if the version number is the same, the integrity property hash is different :

And actually, if we take a look in the node_modules/@abo/testlib we see that the source code is the one we should expect :

So, what happend ? Well as you guessed, the angular cache is responsible for this, let’s see how we can act on this.

Remove the cache and then simply re start the application, which will force the build based on the actual node_modules version of the library. In the latest versions, there is a CLI command that doesn’t exist in version 13.

ng cache clean

rimraf .\.angular\

Of course this solution is far from excellent, but at least it works. The alternative would be to deactivate the cache on the build of the application (we don’t care about the build of the library, but since we are in a single workspace, no cache will be used at all). We will try with a fourth version of the library and the following configuration :

ng cache disable

Then we can rebuild the application anytime we want and whatever the version of the library, we will have the proper version. Of course it’s not a perfect solution because caching would improve our build time, but it’s good to know that even if the hash of the library is ok, even if the local source code is ok, well you really can’t know what version is actually stored in the cache, because if we look into the cache, we can see that the code is already precompiled by Angular :

ng-lib\.angular\cache\13.3.11\babel-webpack (for example)

Conclusion

This local npm registry Verdaccio is really nice to test your Angular library publish skills and parameters. In many cases we don’t really care about the actual version of our libraries other than compatibility, but sometimes, well things happen.

Source code

Source code for this article can be found here angular ng-lib