Migrating from @import to @use

Older projects and tutorials load files with @import. This rule is deprecated: Dart Sass prints a warning for every @import, and Dart Sass 3 will remove it. Sooner or later such a project has to move to @use and @forward. Here is what changes and how to do it with as little manual work as possible.

What was wrong with @import

With @import every variable, mixin and function became global — visible in every file loaded after it:

// styles/main.scss
// The old style
@import "variables";
@import "mixins";
@import "buttons";

Inside _buttons.scss you could write $primary without any @use, but you could not tell where it came from. Two libraries with a $primary silently overwrote each other. And a file imported twice was output twice.

`@import`	`@use`
All names are global	Names through a namespace
A file can be output several times	A module is loaded once
Dependencies are hidden	Each file lists what it uses
Deprecated	The current way

The same code with modules

Each file loads what it needs:

// styles/abstracts/_variables.scss
$primary: #2563eb;

// styles/components/_buttons.scss
@use "../abstracts/variables" as v;
 
.btn {
  background: v.$primary;
}

// styles/main.scss
@use "components/buttons";

.btn {
  background: #2563eb;
}

Built-in functions

The old global functions moved into modules. Sass warns about the old names too:

Old	New
`darken($c, 10%)`	`color.adjust($c, $lightness: -10%)`
`lighten($c, 10%)`	`color.adjust($c, $lightness: 10%)`
`map-get($m, $k)`	`map.get($m, $k)`
`nth($list, 2)`	`list.nth($list, 2)`
`percentage(0.5)`	`math.percentage(0.5)`
`$a / $b`	`math.div($a, $b)`

The migration tool

The Sass team provides sass-migrator, which rewrites files automatically. Install it and run the module migration on the main file:

npm install --save-dev sass-migrator
npx sass-migrator module --migrate-deps styles/main.scss

--migrate-deps also converts every file that main.scss imports. The tool replaces @import with @use, adds namespaces to variables and mixins, and connects built-in modules. A separate division migration replaces / with math.div():

npx sass-migrator division --migrate-deps styles/main.scss

Commit your work to Git before running the tool, so you can review the changes as a diff.

Migrating step by step

In a big project you do not have to convert everything at once. A file loaded with @use may still contain @import inside, and the old and new rules work together during the transition. Start with abstracts/, then convert components one by one, compiling after each step.

Common mistake

Replacing @import with @use mechanically, without namespaces, breaks the build: the components still refer to $primary, and Sass reports Undefined variable. Either add the namespace (v.$primary) or load the file with as *. The migrator does this for you — another reason to start with it.

Thanks for reading!