Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 39 ยท Modules and Architecture

Modules: @use and @forward

Learn the Sass module system: load stylesheets with @use, control namespaces with as, re-export with @forward, and build index files without global scope pollution.

For years the only way to split a Sass project into files was @import. It dumped every variable, mixin and function into one giant global scope, so two files could silently overwrite each other's names, and the same file imported twice produced its CSS twice. The module system replaces that. A file loaded with @use gets its own namespace, is evaluated once, and exposes only what it chooses to expose. A file re-exported with @forward lets you build a tidy public surface for a whole folder.

This lesson covers @use, namespaces, privacy, and @forward. The next lessons build on it: module configuration, the built-in modules, and project architecture.

The playgrounds on this page compile real Sass in your browser. The browser has no file system, so a second file is loaded by a custom importer: @use "mem:tokens" means "the editor labelled _tokens.scss". In your own projects you write plain paths such as @use "tokens" instead.

Loading a module with @use

@use takes a URL (usually a relative path without the extension) and makes that file's members available under a namespace, which defaults to the last part of the path.

SCSS
// _tokens.scss
$brand: #4f46e5;
@mixin card { border-radius: 8px; padding: 1rem; }
@function rem($px) { @return math.div($px, 16) * 1rem; }

// main.scss
@use "tokens";

.button {
  background: tokens.$brand;
  @include tokens.card;
}

You write the namespace, a dot, then the member. Variables keep their $: tokens.$brand. Mixins use @include tokens.card, and functions are called as tokens.rem(24).

Rules for @use:

  • It must appear before any other rules in the file (only @forward, comments and variable declarations that configure the module can come first).
  • The loaded file's CSS is emitted once, at the point of the first @use, however many files load it.
  • Members are not added to the global scope. Two modules can both define $color without conflict.

Partials start with an underscore (_tokens.scss) and are never compiled on their own. You omit the underscore and extension in the URL: @use "tokens" finds _tokens.scss, tokens.scss, _tokens.sass and so on.

@use with a namespace

Change tokens.$brand to a color you like. Rename the variable in _tokens.scss and watch the error: Sass tells you the variable no longer exists in that module, instead of quietly using a stale value.

Choosing the namespace with as

Long file names make long prefixes. Rename the namespace with as:

SCSS
@use "../abstracts/design-tokens" as t;

.card { color: t.$text; }

Use as * to drop the namespace entirely and put members in the current file's scope:

SCSS
@use "tokens" as *;

.card { color: $text; @include card; }

This is convenient for a small project's own variables and mixins, but it brings back the name collision problem. Two as * modules defining the same name is an error (Sass refuses to guess), so use it for your most-used module only, never for a library.

Private members

A name that starts with - or _ is private to its file. Other files cannot see it, which makes it safe to rename later:

SCSS
// _buttons.scss
$-radius: 6px;            // private
$radius: 6px;             // public

@mixin -base { border-radius: $-radius; }    // private helper
@mixin primary { @include -base; background: blue; }

From another file, buttons.$-radius is an error ("Private members can't be accessed from outside their modules"). Underscores and hyphens are interchangeable in Sass names, so $-radius and $_radius are the same private variable.

Loaded once, evaluated once

If _a.scss and _b.scss both contain @use "reset", the reset's CSS appears once in the output. The module is also the same instance for everyone, so state set in it is shared. That is what makes module configuration work, and it is also why a module should never emit CSS that depends on who loaded it.

flowchart TD
  M["main.scss"] --> A["@use 'components/card'"]
  M --> B["@use 'components/button'"]
  A --> T["@use 'abstracts/tokens'"]
  B --> T
  T --> C["CSS emitted once"]

Both components load the tokens, but the tokens module runs once.

Changing a module variable from outside

A public variable can be assigned through its namespace:

SCSS
@use "theme";

theme.$accent: hotpink;   // changes the variable inside the theme module

Assignments from outside work for any public variable, but they run after the module has already been evaluated, so CSS the module emitted earlier does not change. In practice you should configure a module with @use ... with (...) (next lesson) rather than reassigning, because with takes effect before the module runs.

@forward: re-exporting a module

@use is for consuming members. @forward is for publishing them: it makes another module's public members available to whoever loads this file, without making them available inside this file.

SCSS
// abstracts/_index.scss
@forward "tokens";
@forward "mixins";
@forward "functions";

Now one line pulls in the whole folder:

SCSS
@use "abstracts";

.card { color: abstracts.$text; @include abstracts.card; }

A file called _index.scss (or index.scss) is what Sass loads when a URL points to a directory. This is the standard way to give a folder a single public entry point.

show and hide

You can limit what is forwarded:

SCSS
@forward "tokens" show $brand, $accent;           // only these
@forward "internals" hide $-debug, helper-mixin;  // everything except these

Both lists name variables with $ and mixins or functions without it.

Adding a prefix with as

@forward ... as prefix-* adds a prefix to every forwarded name, which avoids collisions when you forward several modules:

SCSS
// _index.scss
@forward "colors" as color-*;
@forward "spacing" as space-*;

If _colors.scss defines $primary, a consumer writes abstracts.$color-primary. Mixins and functions are prefixed the same way.

An index file with @forward

Notice a.$color-text and a.space-stack. Try a.$space-secret and read the error.

@use and @forward in one file

A file can both @use and @forward the same module. Only @use makes the members usable inside the file; @forward only passes them on. Put both kinds of rule at the very top, before any style rules:

SCSS
@forward "config";   // consumers of this file can see config's members
@use "config";       // this file can use them too

When you combine show or hide with as prefix-*, the names in the list are the prefixed names, so with as space-* you hide $space-secret, not $secret.

Common mistakes

  • Writing @use after a rule. Move all @use lines to the top.
  • Forgetting the namespace. $brand alone is "Undefined variable"; write tokens.$brand or load with as *.
  • Using @use where @forward is needed. If an index file only uses a module, consumers of the index will not see its members.
  • Relying on side effects. A module that only emits CSS is fine, but a module whose output depends on being loaded first is a bug waiting to happen.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How do you refer to the variable $brand from a file loaded with @use "tokens"?

    Members of a used module are accessed through the namespace, written as namespace.$variable.
  2. 2. What does @use "tokens" as * do?

    as * puts the members directly into the current file's scope, so you can write $brand.
  3. 3. Which rule re-exports another module's members to files that load this one?

    @forward publishes members to consumers; @use only makes them available inside the file.
  4. 4. A mixin is named -helper inside _utils.scss. What happens when another file writes @include utils.-helper?

    Names that begin with a hyphen or underscore are private to their own file.
  5. 5. If two files both @use "reset", how often is the reset's CSS emitted?

    A module is evaluated once and its CSS appears a single time.

Summary

  • @use "path" loads a module into a namespace; access members as ns.$var, ns.fn(), @include ns.mixin.
  • as name changes the namespace and as * removes it.
  • Names starting with - or _ are private.
  • Every module is evaluated once, and its CSS is emitted once.
  • @forward re-exports members, with show, hide and as prefix-* to shape the public surface; _index.scss makes a folder loadable by name.

Next: Module Configuration and Privacy