Replace Sass @import with @use and @forward in Dart Sass

The decision: stop using @import in Dart Sass

If your project loads Sass partials with @import, Dart Sass treats that syntax as deprecated and emits a warning. The practical problem goes beyond the warning: @import drops a partial’s CSS and variables into the global stylesheet every time it is loaded, which can duplicate output and cause naming collisions across a large codebase.

The useful takeaway is to replace dependency loading with @use, which loads a file as a module under a namespace. A namespace is a prefix that keeps a module’s variables, mixins, and functions separate from other stylesheets. Use @forward only when you need to re-export those members through a single entry point. This guide assumes Dart Sass, the canonical Sass implementation; LibSass and node-sass do not support @use or @forward.

Constraints before you start

• Confirm Dart Sass is the active compiler. Build tools pinned to LibSass or node-sass will fail on @use/@forward syntax.
• Update every partial reference. @use does not create the global variables that legacy @import chains often relied on.
• Avoid circular dependencies. Dart Sass throws a compile error when modules use each other in a cycle.

Supported options compared

Syntax	Purpose	Namespace behavior	CSS output
@import ‘partial’	Legacy partial loading	Members enter the global scope	Can repeat the partial’s CSS on every import
@use ‘partial’	Load a module as a dependency	Members are available under the module namespace, such as partial.$color	Compiles each dependency once per compilation context
@use ‘partial’ as *	Load without a namespace	Members enter the global scope, similar to @import	Compiles once, but reintroduces global collision risk
@forward ‘partial’	Re-export module members	Forwards API members without executing CSS side effects	Does not emit the partial’s own CSS; downstream stylesheets still need @use

Trade-offs

@use prevents global namespace pollution, but you must prefix variables and mixins with the module namespace unless you write @use ‘module’ as *. The latter is convenient for design tokens, but it recreates the collision risk you are trying to remove.

@forward is useful for a single entry point, but it only forwards API members. If a partial contains presentational CSS rules, forwarding it will not emit those rules into downstream stylesheets. You must @use the partial wherever its CSS is needed.

Migration is file-level and mechanical, but it breaks any code that expects variables from one partial to be globally available in another without an explicit @use statement.

Implementation: tokens, components, and an entry point

Suppose your project has two partials: _tokens.scss for design tokens and _button.scss for component styles.

// _tokens.scss
$primary-color: #0a6ebd;
$spacing-unit: 1rem;

@mixin focus-ring() {
  outline: 2px solid $primary-color;
  outline-offset: 2px;
}

// _button.scss
@use ‘tokens’;

.button {
  background-color: tokens.$primary-color;
  padding: tokens.$spacing-unit;
  border: none;
}

.button:focus {
  @include tokens.focus-ring();
}

Create an entry point that forwards the token API so other stylesheets can import one file instead of many.

// _index.scss
@forward ‘tokens’;

In a page stylesheet, load the entry point without a namespace if your team prefers global token access, or keep the namespace for explicit dependencies.

// page.scss
@use ‘index’ as *;
@use ‘tokens’;
@use ‘button’;

.hero-button {
  background-color: $primary-color;
  @include tokens.focus-ring();
}

Compile from the project directory:

sass page.scss public/page.css

Validate the migration

1. Run sass --version in your terminal. Dart Sass is the canonical implementation; if the command is unavailable, install Dart Sass before proceeding. No administrator permissions are required.
2. Compile a test stylesheet that uses @use ‘tokens’ and references tokens.$primary-color. Successful compilation confirms module loading.
3. Search the compiled CSS for duplicated partial output. If _tokens.scss appears only once despite multiple @use statements, the single-compile behavior is working.
4. Temporarily change one @use back to @import. Dart Sass should emit a deprecation warning, confirming the legacy path is still active but discouraged.

Risk: renaming or moving partials breaks module paths. Update relative paths in every @use and @forward statement, then recompile.

Limitations

• @forward does not execute CSS side effects. Presentational CSS in a forwarded partial still requires @use in the stylesheet that needs the rules.
• Circular dependencies between modules are not allowed and throw a compile error.
• LibSass and node-sass cannot compile @use/@forward. Verify your build tool before migrating.

Rollback

Because migration rewrites stylesheet files, keep the pre-migration branch in Git. If the build fails after switching to @use, revert the Sass partials and entry points to @import, then recompile to confirm the previous behavior returns.

Practical check

After migration, open the compiled CSS and search for your token variable value. It should appear in the output wherever used, but the token partial’s source should not be duplicated across multiple imported files. If you see repeated blocks, remove redundant @use statements or consolidate them through a forwarded entry point.