Using Sass @use with Namespaces for Modular Stylesheets

Why @use with namespaces matters

When a stylesheet grows, sharing variables, functions, and mixins across files can lead to duplicated CSS or unpredictable global variable bleed. The Sass @use rule solves this by loading each module a single time, exposing its members under an explicit namespace, and emitting CSS only once. This makes the dependency graph clear and keeps the output size predictable.

How @use works: a worked example

Assume a project with a base stylesheet that defines a colour variable and a button mixin.

/* src/_base.scss */
$primary-color: #0066ff;

@mixin button($bg) {
  background: $bg;
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.25rem;
}

In a component stylesheet we want to use the variable and mixin without polluting the global scope.

/* src/components/button.scss */
@use '../base' as *;   /* imports all members without a namespace */

.btn-primary {
  @include button($primary-color);
}

The as * syntax brings every member of _base.scss into the current file’s scope, so we can reference $primary-color and button directly. If we prefer to keep the namespace explicit, we would write:

@use '../base' as b;

.btn-primary {
  @include b.button(b.$primary-color);
}

When Sass compiles button.scss, it loads _base.scss once, tracks that the variable and mixin have been used, and includes only the necessary CSS in the final output. No duplicate $primary-color definitions or extra button styles appear, even if other files also @use the same base module.

Limitations to keep in mind

• No global bleed: Members that are not explicitly forwarded with @forward stay private to the module. Trying to access $primary-color without the namespace (or as *) will cause a compile error.
• Namespace cannot be omitted unless using as *: Writing @use '../base' without an alias requires you to prefix every reference with the namespace (the filename without underscore or extension).
• Circular dependencies are forbidden: If A.scss @uses B.scss and B.scss @uses A.scss, Sass throws a compilation error.
• CSS output is not cascaded from the module: Top‑level selectors in _base.scss (e.g., a raw h1 {}) are not emitted unless they are included via a mixin or function.

Common pitfalls and how to avoid them

1. Unquoted module paths: Sass expects a quoted string or a plain identifier without special characters. Writing @use base works, but @use ../base.scss (with extension) is ignored and treated as a plain CSS import, causing missing variables. Fix: Omit the file extension and leading underscore, and keep the path quoted if it contains spaces.
2. Filename mismatches: Using hyphens in the filename (base‑utils.scss) while importing with underscores (@use 'base_utils') leads to a “file not found” error. Sass converts hyphens to underscores only for the @import legacy syntax; @use respects the exact filename. Fix: Keep filenames in snake_case and match them exactly in the @use statement.
3. Attempting to @use a plain CSS file: If you point @use at a .css file, Sass treats it as a plain CSS import and does not process any Sass features inside it. Variables or mixins defined in that CSS are unavailable. Fix: Ensure the target file uses the .scss or .sass extension.
4. Assuming global availability without as *: After @use 'base' (no alias), trying to write color: $primary-color; fails because the variable is scoped under the base namespace. Fix: Either add as * or prefix with base..

Practical way to check the result

After compiling, inspect the generated CSS to confirm that each module’s contributions appear only once.

# Compile the entry point
sass src/styles.scss dist/styles.css

# Look for duplicated variable definitions or repeated button styles
grep -n 'primary-color' dist/styles.css

If the variable appears more than once, you likely have an accidental @import or a missing namespace. If the button mixin’s CSS appears only once despite being used in several components, the deduplication is working as intended.

When to choose @use over the legacy @import

For new projects or when refactoring existing stylesheets, @use is the recommended approach because it:

• Provides explicit namespaces that prevent naming collisions.
• Guarantees each module’s CSS is emitted a single time.
• Makes the dependency graph visible to tooling (e.g., IDEs can show where a variable is defined).

Continue using @import only when you need to maintain compatibility with very old Sass versions (<3.7) or when integrating third‑party stylesheets that rely on the global bleed behavior.