In Dart Sass, why does `@use "campus-ui/tokens" with ($radius: 2px)` fail when another file loaded that module first, and how do you fix it?
answer
- !default means only if unset
- configuration belongs to the module
- the first load wins
- configure at the top of the entry point
- @forward can pass defaults on
basics
~20 sA module is loaded once per compilation and keeps the configuration of its first load, so @use ... with() works only on that first load. Configure the library at the top of the entry point, before anything else loads it.
solid answer
~50 sLibrary variables are declared with `!default`, which assigns a value only if the variable is not yet defined or is `null`; `@use <url> with (…)` overrides those top-level `!default` variables. Because a module is evaluated once per compilation and every later `@use` gets that same instance, configuration can only be supplied the first time the module is loaded. If `campus-ui/buttons` already loaded `tokens` unconfigured, a later `@use "campus-ui/tokens" with (…)` is rejected. The fix is ordering: put the configured `@use` first in the entry point, so `buttons`, `cards` and the rest all receive the configured instance; that is also what lets configuration act as a site-wide theme. Inside a library, an index can `@forward "tokens" with ($radius: 4px !default)` to set new defaults that consumers can still override, writing `@forward` before any `@use` of the same module.
code
scss · 9 lines// chemistry-site/main.scss
// Configure first: every later load reuses this configured instance.
@use "campus-ui/tokens" with (
$brand-navy: #20325a,
$radius: 2px
);
@use "campus-ui/buttons"; // loads tokens too, and gets the configured one
@use "campus-ui/cards";go deeper
Recall that !default sets a variable only when it is unset or null, and that @use with() is how a site passes values into a library's !default variables.
Explain that configuration is attached to the single loaded instance of a module, so only the first load may configure it, and that only top-level !default variables are configurable.
When the error appears, trace which file loads the module first, then fix ordering in the entry point or route configuration through one theme module, without forking the library.
Decide how a shared library is configured: a few !default variables through with() for theming, or configuration mixins when consumers need maps and late changes, and document which one you support.
## What !default does A Sass variable declared with the **`!default`** flag is assigned only if that variable is not already defined or its value is `null`; otherwise the existing value is kept. Libraries use it to publish **configurable defaults**: ```scss // campus-ui/_tokens.scss $brand-navy: #1d3a5f !default; $radius: 4px !default; ``` ## Configuring a module with @use … with Under the module system, a consumer passes values into those defaults when loading the module: ```scss @use "campus-ui/tokens" with ($brand-navy: #20325a, $radius: 2px); ``` The rules, all from the Sass documentation: - Only variables written at the **top level** of the module with the **`!default`** flag can be configured. - To combine a namespace and configuration, `as` comes before `with`: `@use "campus-ui/tokens" as t with (…)`. - A module **keeps the same configuration, or lack of configuration, however many times it is loaded**, so `@use … with` can be used only **once per module, the first time that module is loaded**. ## Why a second configuration is refused A module is evaluated once per compilation, and every `@use` of it (from the entry point, from a component partial, from another library file) receives that same instance. Configuration is applied during that one evaluation. So when an entry point reads: ```scss @use "campus-ui/buttons"; // buttons loads tokens, unconfigured @use "campus-ui/tokens" with ($radius: 2px); // too late ``` the first line has already loaded `tokens` without configuration, and the second line asks Sass to configure a module that has already been evaluated. Sass reports an error instead of silently producing two versions of the same variables. Diagnosing it is a matter of tracing load order: 1. Find the first `@use` or `@forward` in the compilation that reaches the module, directly or through another file. 2. Check whether that load passed configuration. 3. Move the configured load ahead of it. ## Fixing it 1. **Configure first.** Put the configured `@use` at the top of the entry point. Every later load, including the one inside `buttons`, gets the configured instance. This is exactly what makes module configuration usable as a **site-wide theme**: configure once, and every component sees the theme. 2. **One configuration point.** Sites with several entry points can keep a small `_theme.scss` that performs the configured `@use`, and have every entry point load it before anything else. 3. **Forward with defaults in the library.** An index file can write `@forward "tokens" with ($radius: 4px !default);`. In a `@forward` configuration, `!default` lets a module change an upstream stylesheet's defaults while still allowing downstream stylesheets to override them, so a consumer's `@use "campus-ui" with ($radius: 2px)` still wins. 4. **`@forward` before `@use`.** If a library file both forwards and uses the same module, writing `@forward` first means a user's configuration reaches the module before the file's own `@use` loads it without configuration. ## When with() is not enough The Sass documentation is candid that configuring modules with `@use … with` is "not particularly flexible". If consumers need to configure many variables at once, pass maps as configuration, or update configuration after the module is loaded, the recommended pattern is a pair of mixins: a `configure()` mixin that assigns the library's private variables with `!global`, and a `styles` mixin that emits the CSS when the caller is ready. Configuration then happens when the caller decides, not at load time, and the library can validate the values it receives. ## Quick reference | Situation | Result | |---|---| | First load passes `with (…)` for top-level `!default` variables | Configured; every later load shares that configuration | | A later load passes `with (…)` after an unconfigured load | Error: the module was already loaded | | `with (…)` names a variable that is not top-level `!default` | Not configurable | | `@forward … with ($radius: 4px !default)` | New default that downstream `with` can still override | | `@forward … with ($radius: 4px)` without `!default` | Fixed value for everyone loading through that file | ## What interviewers listen for - That configuration belongs to the **module instance**, not to the `@use` rule that wrote it. - That load order in the entry point is part of the theme's correctness. - That `!default` means "only if unset", not "force this value". - That a library has two levers, `@forward … with … !default` and configuration mixins, and when each fits.
- What does `!default` add inside a `@forward ... with (...)` clause?It lets an intermediate module change an upstream library's defaults while keeping them configurable. `@forward "tokens" with ($radius: 4px !default)` makes 4px the new default for anyone loading the index, and a consumer's `@use "campus-ui" with ($radius: 2px)` still wins. Without `!default`, the forward's value would be fixed for everyone loading through that file.
- Why should a Sass file that both forwards and uses the same module write `@forward` first?If the `@use` came first, it would load the module without configuration, and configuration a downstream user passes through the `@forward` could no longer be applied, because the module is already loaded. Writing `@forward` first lets that configuration reach the module before the file's own `@use` picks up the same instance.
- When does the Sass documentation suggest mixins instead of `@use ... with`?When you need to configure many variables at once, pass maps as configuration, or change configuration after the module is loaded. The pattern is a `configure()` mixin that sets private variables with `!global`, plus a `styles` mixin that emits the CSS, so the caller controls when configuration happens and when CSS is output.
- Each @use of a module can pass its own with() configuration.
- Any variable in a module can be configured, with or without !default.
- !default forces its value even when the variable is already set.
- The order of @use rules in an entry point never affects the output.
- Writing @use before @forward for the same module makes no difference.