How to change a CSS preprocessor in an Angular project

Angular can maintain any of the major CSS preprocessors. By default the new project is created with the css support, but even after its creation, you can easily switch to sass or less. You can also adjust the preprocessor globally, for all new projects.

What we are going to build

Sass allows us to use special features in stylesheets: variables, mixins and nested rules. In the following examples we are going to change the project’s styles to .scss. However, you can choose .sass extension if you like.

Requirements

Check out your version of Angular, the following guide will work for projects generated with Angular CLI v6 or higher. I’m working on:

$ ng --version

Angular CLI: 6.0.8
Node: 8.11.3
OS: linux x64
Angular: 6.1.1

Change the CSS preprocessor in an existing project

The information about processing styles is kept in the angular.json file (previously angular-cli.json). To update it correctly, run in the main folder of your angular project (where the file resides):

$ ng config schematics.@schematics/angular:component.styleext scss

Use the command rather than editing angular.json manually. You can see that the changes has been added automatically:

// angular.json
…
"defaultProject": "awesome-project",
  "schematics": {
    "@schematics/angular:component": {
      "styleext": "scss"
    }
  }
}

You have to update the extension in all already existing css files: src/styles.scss, src/app/app.component.scss, etc.

Make sure that all components are looking for styles in the updated files:

//src/app/app.component.ts
@Component({
  …
  styleUrls: ['./app.component.scss']
})

Verify the paths used for building the project:

// angular.json
"architect": {
        "build": {
          …
            "styles": [
              "node_modules/font-awesome/scss/font-awesome.scss",
              "src/styles.scss"

Create a new project with the sass preprocessor

If you are creating a fresh project and already know the preprocessor to be used, you can specify it directly during a project creation:

$ ng new awesome-project --style=scss

The angular.json has been created with all required configuration for handling the sass:

// angular.json
{
  …
  "projects": {
    "awesome-app": {
      …
      "schematics": {
        "@schematics/angular:component": {
          "styleext": "scss"
        }
      },
      "architect": {
        "build": {
         …
            "styles": [
              "src/styles.scss"
            ],
          },
          …
        "test": {
          …
            "styles": [
              "src/styles.scss"
            ],
            …
  "defaultProject": "awesome-app"
}

The src/styles.scss file has been already generated and the app.component contains the right path for its styleUrls.  The configuration is finished.

Change CSS preprocessor globally for all new projects

Check out the global configuration

You can establish and read the global settings with the ng config –global command. To find out which settings are being applied to a new project by default, run the command and analyze the output:

$ ng config -g

{
  "version": 1,
  "schematics": {},
  "newProjectRoot": "./",
  "cli": {},
  "architect": {},
  "projects": {}
}

Set sass as the default preprocessor for all new projects

We want to adjust the “schematics” : {}  configuration to build every new project with the sass support. There are several official schematics maintained by the Angular team. As stated in this discussion, when creating a new project, the schematics for ng-new is being applied. So run in the command line:

$ ng config -g schematics.@schematics/angular:ng-new.style scss

Check out the updated global config:

$ ng config -g

{
  "version": 1,
  "schematics": {
    "@schematics/angular:ng-new": {
      "style": "scss"
    }
  },
  "newProjectRoot": "./",
  "cli": {},
  "architect": {},
  "projects": {}
}

Create a new project with:

$ ng new awesome-project

You can see that the project is utilizing the sass:

// angular.json
{
  …
  "projects": {
    "awesome-app": {
      …
      "schematics": {
        "@schematics/angular:component": {
          "styleext": "scss"
        }
      },
      "architect": {
        "build": {
         …
            "styles": [
              "src/styles.scss"
            ],
          },
          …
        "test": {
          …
            "styles": [
              "src/styles.scss"
            ],
            …
  "defaultProject": "awesome-app"
}

The src/styles.scss file has been already generated and the app.component contains the right path for its styleUrls.  The configuration is finished.

Troubleshooting

The global configuration is ignored when creating a new project

In the official Angular CLI documentation for major CSS preprocessors you can find a command for setting a CSS preprocessor on an existing project:

ng config schematics.@schematics/angular:component.styleext scss

It attaches to the end of the angular.json file:

// angular.json
…
"defaultProject": "awesome-project",
  "schematics": {
    "@schematics/angular:component": {
      "styleext": "scss"
    }
  }

I found some recommendation to use the same command – but with -g option for setting a CSS preprocessor universally:

ng config -g schematics.@schematics/angular:component.styleext scss

defaults.styleExt – Value cannot be found

Your project implements an Angular version in which the defaults.styleExt property does not exist. You have to set either:

• the component.styleext property – for changing an existing project;
• the ng-new.style property – for setting the global config for all new projects.

Invalid JSON character: “s” at 0:0

It was a bug and has been already resolved, try updating your Angular version.

In case of other errors

1. If you edited the angular.json file in an existing project manually, revert those changes and run the command:

   $ ng config schematics.@schematics/angular:component.styleext scss

2. Make sure that:
   • all already existing files have updated extension – from .css to .scss (e.g. src/styles.scss, src/app/app.component.scss);
   • all components are pointing to the updated filenames:

     //src/app/app.component.ts
     @Component({
       …
       styleUrls: ['./app.component.scss']
     })

   • verify the paths used for building the project:

     // angular.json
     "architect": {
             "build": {
               …
                 "styles": [
                   "node_modules/font-awesome/scss/font-awesome.scss",
                   "src/styles.scss"

Photo by Anthony Tran on StockSnap