Migrate from CSS to SCSS stylesheets for an existing Angular application

A quick guide to using SCSS in an Angular application that was scaffolded to use the default stylesheet format.

You might have forgotten to provide the style=scss flag or maybe you didn’t know that it existed when you were generating a new Angular application using the Angular CLI, and now you want to switch to using the SCSS stylesheet format in your project, this transition can be daunting in cases where the project has already gotten big.

In this article, I will cover:

• Using an Angular schematics NPM package to perform the migration with just one command.
• The manual way of performing the migration i.e. using the ng cli command.
• Using the NPM package renamer to perform the migration

I will not cover what SCSS and Angular Schematics are in this article because I presume you know what these are. You can read on a great Angular Schematic series of articles on inDepth.dev

Normally, to generate a new Angular project that uses SCSS stylesheets using the Angular CLI, you’d have to run the following command.

ng new my-scss-app --style=scss

A quick and easy way to perform the migration is to use the schematic NPM package schematics-scss-migrate. Read more on what this schematic package does on NPM.

schematics-scss-migrate

Using the NPM package schematics-scss-migrate.

To migrate your project using this package, all you have to do is to install the package, ideally as a dev-dependency and run the command below under your project workspace dir.

NOTE: You can use — dry-run=true for testing before doing the actual migration.

ng g schematics-scss-migrate:scss-migrate

And that’s it, the above command did the following.

• Renamed all the stylesheets in the src folder recursively.
• Altered the styleUrls value to point to the new file names for the stylesheet in the component classes relative to the component style files.
• Updated the component styles schematics value in the angular.json file or creates one if the schematic does not exist.
• And renamed styles.css references to .scss in the angular.json file

The manual migration method using the ng CLI

NOTE: For Angular CLI versions older than v6 beta, use ng set in place of ng config.

With a change that came with Angular 9, styleext was renamed to style, if you are on version 9 or later, then your command should be

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

Or you can directly set the schematics in the angular.json config file like the below:

"schematics": {
    "@schematics/angular:component": {
      "style": "scss"
    }
 ...
  }

After that, in the angular.json file, change the file extension of the style.css for your project build and test options to style.scss, refer to the below.

{
 "projects": {
     "your-project-name": {
         ...
            "architect": {
             "build": {
                 "options": {
                     "styles": [
                           "src/styles.css" // update
                           ...
                        ]
                        ...
                    }
                    ...
                },
               "test": {
                   ...
                     "options": {
                   ...
                       "styles": [
                         "src/styles.css" // update
                       ],
     }
     },
            }
        }
    }
}

And then to rename the stylesheet files, follow the instructions below.

Changing the project’s stylesheet files from .css to .scss file extensions using the renamer NPM package.

To achieve this the most efficient way, I have used a NPM package: renamer.

I have installed the package globally (You can use npx if you want to)

npm i -g renamer

Now, in the terminal, navigate to the project’s src directory.

Before you continue with running commands on your project, stage — commit your work and maybe switch to a new branch to play around with the renamer tool, you can read more on it here.

Let’s test the tool, NOTE: Use the -d flag for a DRY-RUN of the command

The above command renames all files with .CSS to .SCSS in the current working directory which is src since we had navigated to it, this is because of the wildcard/glob at the far end of the command which is “*”, now that we see that the command does what it should, go ahead and remove the -d flag from the command to apply the execution.

The changes where successful

Before command

After command

Note that we have run the command twice on the styles.scss because of our testing in the beginning, now it is styles.scss, so correct that.

Now that we have achieved that, we have to change the source to use the new files extension, as a good Angular convention suggests that we name the stylesheets of our components by suffixing them with .component.css as our component files, it becomes easy to refactor the project as a whole at one go, for me it was at least, I had searched globally for any file with the .component.css reference using the shortcut Ctrl + Shift + f and replace all with Ctrl + Shift + h.

My project has many references so the shortcuts and following the Angular conventions saved me some time.

The project’s build is green, so yeah that is how you can quickly migrate from .css to .scss stylesheets for an existing Angular application.

It is up to you which method you pick, but for me, the schematic-scss-migrate package seems to be the easiest approach and also considering that it is safe to use because you can use the dry-run option so you can verify the migration.

I hope you enjoyed reading it.

See the source of schematics-scss-migrate below:

Teebo/scss-migrate