Breaking Change

Angular SCSS @import Is Dead — Here’s How to Migrate to @use and @forward

Keep the warnings of deprecation silent for good

Source : Nagaraj

The terminal opened with your command and showed deprecation warnings which filled the screen during every ng build execution. Every. Single. Build. The Angular team has moved away from SCSS @import since they need you on the new module system.

The worst part isn’t the warnings. The emergency situation only becomes apparent after you have already shipped. But Dart Sass removed @import support in version 3.0 and Angular will do the same in its next major release.

The process does not progress through a gradual decline. It is a countdown. The following sections show you the specific changes needed with their corresponding reasons.

What @import Gets Wrong Under the Hood

The Dart Sass compiler imports all content from the @import ‘variables’ statement to the specified location which becomes accessible throughout the entire project. The variables file gets imported three times when three components use it because the system does not have deduplication features and does not restrict access to shared components.

The system establishes an invisible trap which transforms every variable and mixin from that file into a globally accessible entity. The system records a change as a global change which activates whenever you implement modifications to that variable. The result is an @import-driven bug that creates invisible spacing problems across unrelated components when a single variable changes.

The Migration: 4 Practical Steps

The SCSS file uses identical stylesheet rules which apply to different modules. You need to implement specific changes for every file type.

Step 1 — Replace @import in Variables Files

Your first task involves selecting your primary imported file which typically corresponds to _variables.scss or _tokens.scss. The content of this file remains unchanged while all files that use it will be affected.

The old pattern imported variables directly into the global namespace. The new pattern loads them under a namespace you control.

Step 2 — Migrating Mixins with @use

The usage of mixins requires developers to follow the same rules as other functions. Developers encounter their first major challenge through the namespace prefix requirement which they must use when including mixins.

You can access mixins from the dedicated file _mixins.scss using the namespace which you defined through @use. Access requires a defined namespace because the system restricts entry without it.

Step 3 — Create an _index.scss with @forward

The @forward rule provides a solution which replaces the existing method that required you to share all partials through a single @import statement bringing in all styles from your styles/all file.

The _index.scss file needs to be created in the folder, using @forward for re-exporting all partials. The folder now allows files to use @use ‘styles’ which provides them access to all content.

Some Angular Idiosyncrasies

The only aspect that Angular component encapsulation alters is that SCSS from a component’s styleUrls file exists only within that particular component. Your shared partials which include _variables.scss and _mixins.scss must be used by each component because they exist outside that component’s access area.

You need to create a separate @use declaration in each component SCSS file because a global styles.scss does not share its namespace with components. The SCSS file of each component functions as an independent module entry point.

Using additionalData in angular.json (The Shortcut)

The need to repeat @use ‘../styles’ as s in every file becomes tedious when multiple components import identical variables. The SCSS preprocessor of Angular provides automatic @use injection through its preprocessor configuration options.

The Angular CLI configuration provides a supported shortcut which functions as an official path to follow.

Using the Official Sass Migration Tool

Sass provides an official migration tool which handles the automatic conversion process from @import statements to @use statements. The process becomes lengthier when you have more than 20 SCSS files to convert manually.

Execute the program one time to evaluate its results which you then correct through manual work on the exceptional cases. The system can complete 80 to 90 percent of the tasks automatically for most Angular projects that it processes.

I launched the migration tool and created a code commit without reviewing the changes because I then dedicated half a day to search for a malfunctioning mixin which the tool had incorrectly renamed. Dry run. Always.

How @use Changes Your Angular Material Theme

The most complex migration situation arises from theming which provides more challenges than variable files do. Your attempt to override Angular Material or a custom theme through partial imports and variable redefinitions will result in @use creating an intentional pattern break.

The latest Angular Material setup requires users to implement @use ‘@angular/material’ as mat together with its theme configuration functions. Users who continue to use the previous Material theme setup based on @import must perform a separate theme file migration.

The module system demonstrates superior performance across all quantifiable metrics because it delivers quicker compilation times and establishes consistent variable visibility while preventing unexpected style leaks. The migration process creates an unexciting task which requires systematic execution. I observe teams who keep postponing their work until Angular introduces a mandatory breaking change, which makes them start working under pressure. You already know what happens then.

The question needs careful consideration: if @import was so obviously broken from the start, why did it take Sass a decade to develop a replacement — and why are most live Angular applications still depending on it today?

Thank you for reading! 👏👏👏 Hit the applause button and show your love❤️, and please follow➡️ for a lot more similar content! Let’s keep the good vibes flowing!