Migrating Sass Stylesheets from @import to the @use Rule for Modular, Namespaced Code

Desired outcome

Replace legacy @import statements with the modern @use rule so that each Sass module is loaded only once, its members are namespaced, and you can safely override variables for theming without editing the module itself.

Prerequisites

• Dart Sass version 1.23 or newer (the version that introduced @use and warns on @import).
• A Sass project with at least one stylesheet that currently uses @import to pull in utilities, mixins, or variables.
• Basic familiarity with Sass syntax (variables, mixins, functions).

Focused procedure

1. Check the compiler version

   Run sass --version in your project root. Ensure the output shows 1.23.0 or higher.

   sass --version
   # Dart Sass 1.80.0
   

2. Identify a module to migrate

   Pick a file that is imported many times, such as utilities.scss containing shared variables and mixins.

   /* utilities.scss */
   $primary-color: #0066ff;
   
   @mixin button-size($padding: 0.5rem) {
     padding: $padding;
     font-size: 1rem;
   }
   

3. Replace @import with @use

   In each stylesheet that previously did @import 'utilities';, write:

   /* main.scss – before */
   @import 'utilities';
   
   .button {
     @include button-size;
     background-color: $primary-color;
   }
   
   /* main.scss – after */
   @use 'utilities';
   
   .button {
     @include utilities.button-size;
     background-color: utilities.$primary-color;
   }
   

   If you prefer to avoid the namespace prefix, you can use @use 'utilities' as *; to bring members into the local scope, but keep in mind that this re‑introduces the risk of name collisions.

4. Override variables with the with clause

   To theme a component without editing utilities.scss, pass a with block:

   /* theme-dark.scss */
   @use 'utilities' with (
     $primary-color: #ff6600
   );
   
   /* Use the overridden variable */
   .header {
     background-color: utilities.$primary-color;
   }
   

5. Re‑export selected members with @forward

   Create a public API file that forwards only what you want consumers to see:

   /* _api.scss */
   @forward 'utilities' {
     hide $primary-color; /* keep internal variable private */
     show button-size;   /* expose the mixin */
   }
   

   Other stylesheets then do @use 'api'; and access api.button-size.

6. Remove remaining @import lines

   Run a search across your .scss files for @import. Each hit should be replaced or justified (e.g., third‑party CSS that cannot be converted).

7. Compile and verify

   Run the Sass compiler on your entry point:

   sass src/main.scss dist/main.css --no-source-map
   

   Check the output CSS for the expected values and that no duplicate rules appear.

Expected checks

• The compiler finishes without the deprecation warning: "Warning: @import is discouraged and will be removed in future versions."
• Each module’s contents appear only once in the generated CSS (you can verify by adding a unique comment inside a module and confirming it appears a single time).
• Variable overrides via the with clause affect the compiled output as intended.
• If you added a linter rule such as stylelint-plugin-no-import, it reports zero @import occurrences.

Recovery options

• If a module fails to compile after conversion, revert the specific file to its previous @import line while you investigate the issue.
• Keep a backup of the original stylesheet set (e.g., copy the src folder) before beginning the migration.
• Run the compiler with the --quiet flag to suppress warnings temporarily while you verify that the CSS still matches the expected visual output.