Angular unused css detection

Breaking changes in version >= 4.0.0

- sass lib has been upgraded to latest version therefore custom importer configuration needs to be changed,
refer to: https://sass-lang.com/documentation/js-api/interfaces/FileImporter
-

Quick setup

Run via API

``
import { NgxUnusedCSS } from 'ngx-unused-css';

const result = new NgxUnusedCSS(config).instance.run();
`

Run via CLI

npx ngx-unused-css --init

npm i -D ngx-unused-css

Add script into package.json and run it:

"scripts": {
...
"unused-css": "ngx-unused-css"
...
}

How does it works

- it finds all .html files inside the project and then pairs it with their styling files;
e.g. app.component.html > app.component.scss
- if pair is matched then it will compare unused css using PurgeCSS library
- SCSS will be automatically compiled before the matching phase
- some system selectors like :host or ::ng-deep will be ignored
- with configuration it is possible to extend global selectors to ignore
- configure ignore per file in case CSS class is applied dynamically; ENUMS or based on backend model

Installation

Global: npm install -g ngx-unused-css

or

Local: npm install ngx-unused-css --save-dev

$3

.ngx-unused-css.json

Usage

Run in CLI if installed globally like: ngx-unused-css

or add it to package.json > scripts: "unused-css": "ngx-unused-css" and run in CLI: npm run unused-css

_Optionally, override config path with CLI param: ngx-unused-css --config=otherConfig_

Options

$3

- Type: String
- Default: null

Path to a project, for Angular it is usually src/app

$3

- Type: String
- Default: .scss

Styling extension used in the project, options are: scss | sass | css

$3

- Type: String
- Default: null

Path to global styles, usally it is src/styles.scss

$3

Custom importer handler, more details here: https://sass-lang.com/documentation/js-api/interfaces/FileImporter

$3

Refer to original documentation: https://github.com/sass/node-sass#includepaths

$3

- Type: Array
- Default: null

Selectors to ignore, they can be defined globally (as an string) or specific per file (as an object).
This comes useful when class is applied based on the value from the backend, e.g.

[ngClass]="model.status.toLowerCase()" class is dervied from the backend so there is no possibility to do the analysis.

Special: global as a string, or Object as a file specific

$3

#### file

- Type: String
- Default: null

Path to css file, relative to projectPath

#### selectors

- Type: Array
- Default: null

Array of selectors inside the file

#### all

- Type: Boolean
- Default: false

If set as true it will ignore selectors property (if defined) and will ignore whole file

Example: _Ignore .dynamic-class in app.component.scss_:

`
{
file: "app.component.scss",
selectors: [".dynamic-class"]
}
`

Example: _Ignore whole app.component.scss_:

`
{
file: "app.component.scss",
all: true
}
`

Example: _Ignore ng-star globally and .test-2 inside test.component.scss file_:

`
{
"path": "src/app",
"ignore": [
"ng-star",
{
"file": "test.component.scss",
"selectors": [".test-2"]
}
]
}
`

ngClass handling

If ngClass is found on the element, same element will be duplicated with all possible combination of the classes on the same level and template will be then compared with css definition to match if all possible combinations are used

Example:

`



`

To compare against CSS it will recompile html with all possible cases:

`



``

NOTE: This library will not detect nested ngClasses

Special cases

Template files that are not matching their styling counter part will be ignored