With Dart Sass's module system, how does @use differ from the deprecated @import in how members are named, loaded and kept private?
answer
- one global scope versus files
- namespace from the URL's last part
- loaded once per compilation
- leading - or _ means private
- @import deprecated in 1.80.0
basics
~20 s@use loads a file once per compilation as a module whose members are namespaced (tokens.$navy), visible only to the loading file, and private when named with - or _. @import shared one global scope; Dart Sass 1.80.0 deprecated it.
solid answer
~50 s`@import` put every variable, mixin and function into one global scope, so libraries prefixed every name, any file could silently depend on a member an earlier import defined, and each imported file ran and emitted its CSS again every time. `@use` treats a file as a **module**: members are reached through a namespace, by default the last part of the URL (`@use "campus-ui/tokens"` gives `tokens.$brand-navy`), renamed with `as t` or dropped with `as *`. A module is loaded once per compilation and its CSS is emitted once, however many files use it. Members are visible only in the file that wrote the `@use`, and names starting with `-` or `_` are private. `@use` rules sit at the top level, before other rules except `@forward`. Sass `@import` has been deprecated since Dart Sass 1.80.0 and is due for removal in Dart Sass 3.0.0.
go deeper
Recall that @use namespaces members by the file name and that Sass @import is deprecated. Be able to write a @use rule and reference a variable through its namespace.
Explain load-once semantics, per-file visibility, private members and the as clause, and why @import's single global scope pushed libraries into long prefixed names.
Diagnose what breaks when files switch to @use: members that were only reachable through global leakage, and output that shrinks because repeated imports stop duplicating CSS.
Treat the module system as an API boundary for shared styles: namespaces and private members let a library change internals safely, which is the case for retiring @import across teams.
## Two ways of loading another stylesheet Sass has had two rules for pulling one stylesheet into another. The original, **`@import`**, borrowed CSS's at-rule name but did something different with it: it inlined the other Sass file at compile time and merged its variables, mixins and functions into **one global scope**. The **module system**, `@use` and `@forward`, replaced that model, and as of **Dart Sass 1.80.0** Sass's `@import` is deprecated. (The browser's own CSS `@import`, which fetches a stylesheet at runtime, is a separate matter.) ## What was wrong with @import The Sass documentation lists the problems directly: - Every variable, mixin and function became **globally accessible**, so neither people nor tools could tell where a member was defined. - Because everything was global, libraries had to **prefix every member** (`$campus-brand-navy`) to avoid collisions. - **`@extend` was global too**, so an extend could reach rules its author never saw. - Each file was **executed and its CSS emitted every time** it was imported, slowing compilation and bloating the output. - There was **no way to keep members private** to a file. ## How @use behaves `@use "campus-ui/tokens";` loads the file as a **module**: 1. **Namespaced access.** Members are reached through a namespace, by default the last component of the URL without its extension: `tokens.$brand-navy`, `@include tokens.focus-ring;`, `tokens.spacing(2)`. 2. **Choosing a namespace.** `@use "campus-ui/tokens" as t;` shortens it; `as *` removes it so members are used by bare name. The docs recommend `as *` only for stylesheets you write yourself, because a library that later adds a member can collide with yours. 3. **Loaded once.** However many files `@use` the same module, its CSS is included exactly once in the compiled output, and every `@use` shares one instance of it. 4. **Visible only where loaded.** Members are available only in the stylesheet that wrote the `@use`. A file that needs `tokens.$radius` writes its own `@use`, which costs nothing because of the previous rule. A library that wants one entry point re-exports members with `@forward`. 5. **Private members.** A member whose name starts with `-` or `_` (`$-grid`) works inside its own file but is invisible to every stylesheet that loads the module. 6. **Placement.** `@use` rules come before any other rules except `@forward` (variables may be declared before them for configuration), and they sit at the top level of a file, whereas `@import` could be nested inside a style rule. ```scss // campus-ui/_buttons.scss @use "tokens"; .btn-primary { background: tokens.$brand-navy; border-radius: tokens.$radius; } ``` ## Side by side | Question | `@import` (deprecated) | `@use` | |---|---|---| | How are members named? | One global scope, no namespace | `namespace.member`, renamable with `as` | | Where are they visible? | Everywhere after the import | Only in the file that wrote the `@use` | | How often does a file's CSS appear? | Once per import | Once per compilation | | Private members | Not possible | Names starting with `-` or `_` | | Nested inside a style rule | Allowed | Not allowed; top level only | ## The deprecation timeline Dart Sass 1.80.0 made Sass `@import` rules emit deprecation warnings, together with the **global built-in functions** that have counterparts in the `sass:` modules (for example `map-get()`, which becomes `map.get()` after `@use "sass:map"`). The Sass team has committed to keeping both until **Dart Sass 3.0.0**, which will be released no sooner than two years after 1.80.0; Dart Sass 2.0.0 keeps them as warnings rather than errors. Eventually every `@import` will be treated as a plain CSS `@import`. The `sass-migrator module` command rewrites `@import`-based code automatically, adding namespaces and the `@use` rules that files previously did without by leaning on the global scope. ## What changes in day-to-day code - Short member names become safe: `tokens.$radius` cannot collide with another library's `$radius`. - A forgotten `@use` becomes a compile error instead of a silent dependency on load order. - Built-in functions are loaded the same way: `@use "sass:math";` and then `math.div(…)`. - Plain `.css` files can be loaded with `@use` too; they are included once, but expose no Sass members. - Code review gets easier: every member's origin is visible from its namespace.
- If `_buttons.scss` needs a variable from `_tokens.scss`, is it enough that `main.scss` already wrote `@use "tokens"`?No. Members loaded with `@use` are visible only in the stylesheet that wrote the rule, so `_buttons.scss` writes its own `@use "tokens"`. That costs nothing: the module is still loaded once and its CSS emitted once. Under `@import` the same code worked only because everything shared one global scope and the load order happened to be right.
- When would you write `@use ... as *`, and what is the risk?It drops the namespace, so members are used by bare name, which is convenient for your own small helper files. The Sass docs advise it only for stylesheets you write yourself: a third-party module that later adds a member with the same name as one of yours produces a name conflict you did not choose.
- Can `@use` load a plain `.css` file?Yes. `@use "code"` can load `code.css`, and its rules are included as-is, once. A CSS file loaded as a module exposes no variables, functions or mixins, and any Sass-only syntax inside it is an error, so it is a way to include CSS, not to share Sass members.
- @use is @import with a new keyword; both share one global scope.
- Each @use of a module emits that module's CSS again.
- Members loaded by @use in main.scss are visible in every file it loads.
- A leading underscore on a variable name has no effect on who can use it.
- @import was already removed in Dart Sass 2.0, so old stylesheets fail today.
Assumes Dart Sass 1.105 (major 1): Sass @import has been deprecated since 1.80.0 and is due for removal in Dart Sass 3.0.0.