Sass & SCSS Modules Explained

Understanding Sass & SCSS Modules

Sass modules provide a modern, predictable way to organize styles using @use and @forward. Modules give you explicit namespaces, clearer dependency flow, and safer sharing of variables, mixins, and functions.

In this tutorial you will learn what Sass modules are, why they replace @import, how to create modules and entry modules, how to import with @use, how to re-export with @forward, practical file layouts, and best practices.

What Are Sass and SCSS Modules?

Sass modules are files you load with @use and manage with @forward. Each module exposes members through a namespace. Modules prevent global pollution and make dependency relationships explicit, which helps avoid accidental collisions.

• Modules use the @use rule to import and scope members
• The @forward directive re-exports members from one module to another
• Modules replace legacy @import directive for modern workflows

$primary: #3498db;
$accent:  #2a73cc;

Why Use Sass Modules Instead of @import?

Sass modules give predictable scoping and avoid the implicit global behavior of @import rule. With modules you control the namespace and you can re-export a curated public API, which makes large codebases easier to maintain.

• Explicit namespaces reduce naming conflicts
• @forward creates a clear public interface
• Modules make dependency order less error prone

How to Create a Sass Module

Create a normal Sass partial and export its members by leaving them public. A Sass module is just a partial that you import with @use. Name modules by purpose to make them discoverable.

• Name partials by responsibility, for example _colors.scss
• Keep each module focused on one concern
• Prefer clear member names rather than relying on globals

@function rem($px) {
  @return $px / 16 * 1rem;
}

@mixin card($pad: 16px) {
  padding: rem($pad);
  border-radius: 6px;
  box-shadow: 0 2px 6px rgba(0,0,0,0.08);
}

Importing SCSS Modules with @use

Use @use rule to bring a Sass module into scope. By default members are namespaced by the module name, however, you can add an alias with as keyword to shorten references.

• Use @use "module" to bring members under that module
• The @use rule isolates module state from other files

@use "colors";
@use "mixins" as mx;

.button {
    background: colors.$primary;
    @include mx.card(12px);
}

@use colors
@use mixins as mx

.button
    background: colors.$primary
    +mx.card(12px)

.button {
    background: #3498db;
    padding: 0.75rem;
    border-radius: 6px;
    box-shadow: 0 2px 6px rgba(0,0,0,0.08);
}

Re-exporting SCSS Modules with @forward

Use @forward directive to create a single public module that gathers and re-exports selected members from other Sass modules. This centralizes your API and simplifies imports for consumers.

• @forward exposes members from another module
• Use as keyword to rename or hide members if needed
• Forwarding creates a curated module surface

@forward "colors";
@forward "mixins";

Building a Central Module Entry Point

Create a single entry module that forwards the modules you want to expose. Consumers then only need to use this entry file to access your design system.

• Create an index module that forwards submodules
• Keep the entry module stable and minimal
• Document which members of the module are public

/sass
    /modules
        _colors.scss
        _mixins.scss
        _tokens.scss
        _index.scss   // forwards modules
    main.scss

Using Namespaces and Aliases in Sass Modules

Sass namespaces prevent collisions and clarify where styles come from, while aliases shorten long module names to keep code readable. Consistent alias patterns should be used across the project.

• Namespace defaults to the file name
• Use the as for short prefixes like c or t
• Avoid duplicate aliases across modules

@use "modules/index" as ui;

.card {
    background: ui.$card-bg;
    @include ui.card;
}

Folder Structure for Organizing SCSS Modules

Choose a predictable folder layout so project contributors can locate modules quickly. Group files by role instead of layer when it improves reuse.

• tokens for colors, spacing, typography
• utilities for mixins and functions
• components for reusable UI parts
• pages for page-specific styles

/sass
    /modules
        _index.scss
        _colors.scss
        _tokens.scss
        _mixins.scss
    /components
        _button.scss
        _card.scss
    main.scss

Best Practices

Use Sass modules to keep code encapsulated and clear. Limit unnecessary forwards, prefer explicit imports with consistent aliases, and document the public API in the module index.

• Keep modules focused on one purpose
• Use forwards only when really needed
• Document public exports in the index
• Follow consistent aliasing, e.g. c for colors
• Avoid circular dependencies through clear layering
• Verify imports when refactoring multiple modules