Migrating from @import
Understand why @import is deprecated and how @use replaces it.
Syntax
sass-migrator module --migrate-deps main.scssThe old @import rule is deprecated and will be removed from Dart Sass. It had real problems that @use and @forward fix.
Problems with @import
- Everything was global — every variable and mixin from every file leaked into one namespace, causing collisions.
- Files could be imported many times, duplicating CSS.
- There was no concept of private members.
Migrating
Replace @import with @use (adding namespaces) or @forward. The official sass-migrator tool automates most of the work.
| Old | Modern |
|---|---|
@import 'colors'; | @use 'colors'; |
$brand | colors.$brand |
Example
# Install the migrator
npm install -g sass-migrator
# Convert @import to @use across a file and its dependencies
sass-migrator module --migrate-deps main.scss
# It rewrites @import into @use and adds namespaces automatically.When to use it
- A developer migrates a legacy project from @import to @use to eliminate duplicate CSS output caused by the same partial being imported from multiple files.
- A team uses the sass-migrator tool to automatically convert all @import statements in a codebase to @use with proper namespaces.
- An open-source library removes all @import usage before publishing so it works correctly in Dart Sass without deprecation warnings.
More examples
Old @import vs new @use
Side-by-side comparison showing @import with unprefixed variable access replaced by @use with explicit namespaced access.
// Old — deprecated
@import 'variables';
@import 'mixins';
.btn { color: $primary; }
// New — recommended
@use 'variables' as v;
@use 'mixins' as mx;
.btn { color: v.$primary; }Running the sass-migrator tool
Uses the official sass-migrator CLI to automatically rewrite @import statements to @use across all .scss files.
# Install the migrator
npm install -g sass-migrator
# Migrate a whole directory in place
sass-migrator module --migrate-deps scss/**/*.scssProblems @import caused
Illustrates the core @import problem: every file that imports a partial gets a full copy in the output, bloating production CSS.
// file-a.scss
@import 'reset'; // reset CSS output here
// file-b.scss
@import 'reset'; // reset CSS output again — duplicated!
// With @use, the file is only compiled once
// regardless of how many files load it.
Discussion