Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 39 ยท Migration and Best Practices

Migrating from @import to the Module System

Move a legacy Sass codebase from @import and global functions to @use, @forward and built-in modules: why it matters, the sass-migrator tool, a manual plan, and traps to avoid.

Most Sass code written before 2019 uses @import, global functions like darken(), and / for division. All three are deprecated: they still compile, with warnings, but Dart Sass 3.0 will remove them. Migrating is not urgent for a small stylesheet, but it is worth doing for any project you plan to keep alive, and it is an unusually safe refactoring because the compiler tells you exactly what broke.

This lesson explains what changed and why, shows the same code before and after, introduces the automatic migrator, and gives a step-by-step plan for doing it by hand in a large project.

What was wrong with @import

@import "file" is not a module system; it pastes the other file into this one:

  • Everything is global. A variable $gap in one partial overwrites $gap from another, silently, depending on load order.
  • No privacy. Helper variables meant for one file are visible everywhere.
  • No dependency declaration. A partial that uses $brand works only if some other file happened to be imported first. Open it alone and it fails.
  • Duplicate output. Importing a file twice emits its CSS twice.
  • Slow. Each import re-evaluates the file in the current scope; big projects spent seconds on redundant work.
  • Name prefixes. Libraries had to prefix every name ($bs-, mat-) to avoid collisions.

The module system fixes all of these: namespaces, once-only evaluation, privacy and explicit dependencies.

Before and after

Here is a small legacy project compiled with @import:

Legacy: @import and global functions

It works (the playground hides the deprecation warnings), and it contains three problems the compiler would warn about in a real build: @import, the global darken and percentage, and 1 / 3 as division.

Now the migrated version:

Migrated: @use and built-in modules

The output is the same. The new source says where every name comes from (vars.$brand, mixins.rounded) and which Sass modules it needs.

The automatic migrator

The Sass team publishes a tool, sass-migrator, that rewrites files for you:

Terminal
npm install -g sass-migrator

# Rewrite main.scss and every file it imports (--migrate-deps)
sass-migrator module --migrate-deps src/main.scss

# Preview without writing files
sass-migrator module --dry-run --migrate-deps src/main.scss

# Add load paths if you import from other folders
sass-migrator module --load-path=node_modules --migrate-deps src/main.scss

What the module migrator does:

  • Replaces @import with @use (or @forward in files that only re-export).
  • Adds namespaces to every reference to a moved variable, mixin or function.
  • Swaps global built-ins for sass:math, sass:map, sass:color, sass:list and so on.
  • Removes name prefixes that existed to avoid collisions (it asks for the prefix via --remove-prefix).

A second migrator fixes division:

Terminal
sass-migrator division "src/**/*.scss"

Always review the diff (commit first, so you can see it) and compile before and after, comparing the CSS. The migrator is good, but dynamic code (meta.call, names built from strings, heavily conditional imports) needs a human.

A manual plan for big projects

  1. Update Sass to a current Dart Sass and pin the version.
  2. Collect the warnings. Compile with --verbose to list every occurrence, or run with --fatal-deprecation=import on a branch to see the first failures.
  3. Migrate leaf files first. Start with partials that import nothing (tokens, functions, mixins) and convert them to modules; give each its own @use "sass:..." lines.
  4. Add an index file per folder with @forward so consumers write one @use. See project architecture.
  5. Migrate the consumers (components, layout), adding @use for every dependency each file really has.
  6. Fix division and global functions with the migrator or search and replace (darken( -> color.adjust(, map-get( -> map.get().
  7. Compare output. Compile the old and new versions with --style=expanded and diff the CSS. Reordered rules are acceptable; missing or changed declarations are not.
  8. Remove @import completely and turn on --fatal-deprecation=import in CI.

Both systems side by side

You can migrate gradually because the two systems interoperate:

  • A file loaded with @use can itself contain @import (old code works inside a module).
  • A file loaded with @import can contain @use (its members then become global for the importer, which is how you expose a module to an old codebase).
  • @forward plus a compatibility partial lets legacy code that expects global names keep working while you convert:
SCSS
// _legacy.scss: expose the new modules as globals for old files that still @import
@forward "tokens";
@forward "mixins";
SCSS
// An old file
@import "legacy";   // $brand, rounded(), ... are visible again (members of forwarded modules become global)

Plan to delete such shims once nothing imports them.

Third-party libraries that still use @import

Some popular frameworks have been slow to move. Bootstrap 5, for example, still uses @import internally and asks you to import its pieces in order. Until they migrate:

  • Use their documented import approach, and suppress the noise with quietDeps: true or --silence-deprecation=import (the library is a dependency, not your code).
  • Do not mix your modules into their import chain unless the docs show how; configure through the variables they expose.
  • Watch release notes: when the library ships a modules version, you switch in one step.

Typical traps

  • Variables you used to set before importing ($primary: red; @import "lib";) now require @use "lib" with ($primary: red), and the library must mark it !default. See module configuration.
  • Missing @use in a leaf. A partial that quietly used a global now errors with "Undefined variable". That is the point: add the @use.
  • Circular dependencies. Imports that depended on order may form a cycle. @use forbids it; extract the shared part into a third file.
  • @extend across files now requires that the extended selector's module is part of the dependency graph (@use it).
  • Mixins that relied on global state (a variable changed by one component and read by another) must be rewritten to take arguments or use a module-level configuration.
  • Relative url() paths do not change, but @use URLs are resolved relative to the file that contains them, which may differ from how the old import resolved nested imports.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is @import deprecated?

    The module system replaced it with namespaces, privacy and once-only evaluation.
  2. 2. Which command migrates a project and everything it imports?

    The module migrator with --migrate-deps rewrites the entry file and its dependencies.
  3. 3. How should darken($brand, 8%) be written in modern Sass?

    The color module replaces the global lighten/darken family with adjust, scale and change.
  4. 4. In which order should you migrate files?

    Dependencies must already be modules when their consumers start using @use.
  5. 5. A library that still uses @import floods you with warnings. What is a sensible response?

    You cannot fix a dependency's code, so hide its noise and watch for a modules release.

Summary

  • @import, global functions and / division are deprecated and will be removed in Dart Sass 3.0.
  • The module system adds namespaces, privacy, explicit dependencies and once-only evaluation.
  • sass-migrator module --migrate-deps and sass-migrator division automate most of the work; review the diff and compare compiled CSS.
  • Migrate leaf files first, add index files with @forward, then consumers; keep a temporary compatibility partial if needed.
  • Use quietDeps for libraries you cannot change, and --fatal-deprecation in CI to stay migrated.

Next: Performance and Output Size