Migrating style.scss
This migration converts stylesheets that use / as division to use the
built-in math.div function instead.
By default, the migrator converts / operations to math.div even when it
isn’t sure that it will be division when evaluated. It only leaves them as-is
when it can statically determine that they’re doing something else (such as when
there’s no SassScript involved, or when one of the operands is a string). The
math.div function currently functions identically to the / operator, so
this is safe to do, but may result in new warnings if one of the arguments to
math.div at runtime is not a number.
If you want to avoid this behavior, you can pass the --pessimistic flag. With
this flag, the migrator will only convert / operations that it knows for sure
are doing division. This will prevent any unnecessary math.div conversions,
but it’s likely to leave some division unmigrated if it can’t be statically determined.
This migration converts stylesheets that use the old @import rule to load
dependencies so that they use the Sass module system via the @use rule
instead. It doesn’t just naïvely change @imports to @uses—it updates
stylesheets intelligently so that they keep working the same way they did
before, including:
Adding namespaces to uses of members (variables, mixins, and functions) from
other modules.
Adding new @use rules to stylesheets that were using members without
importing them.
Converting overridden default variables to with clauses.
Automatically removing - and _ prefixes from members that are used from
other files (because otherwise they’d be considered private and could only
be used in the module they’re declared).
Converting nested imports to use the meta.load-css() mixin instead.
⚠️ Heads up!
Because the module migrator may need to modify both member definitions and
member names, it’s important to either run it with the --migrate-deps
option or ensure that you pass it all the stylesheets in your package or application.
$ cat style.scss
$body-bg: #000;
$body-color: #111;
@import "bootstrap";
@include media-breakpoint-up(sm) {
.navbar {
display: block;
$ sass-migrator --migrate-deps module style.scss
$ cat style.scss
@use "bootstrap" with (
$body-bg: #000,
$body-color: #111
@include bootstrap.media-breakpoint-up(sm) {
.navbar {
display: block;
The module migrator needs to be able to read all of the stylesheets depended on
by the ones it’s migrating, even if the --migrate-deps option is not
passed. If the migrator fails to find a dependency, you’ll get an error.
$ ls .
style.scss node_modules
$ sass-migrator module style.scss
Error: Could not find Sass file at 'dependency'.
1 | @import "dependency";
| ^^^^^^^^^^^^
style.scss 1:9 root stylesheet
Migration failed!
$ sass-migrator --load-path node_modules module style.scss
If you use a load path when compiling your stylesheets, make sure to pass
that to the migrator using the --load-path option.
Unfortunately, the migrator does not support custom importers, but it does have
built-in support for resolving URLs starting with ~ by searching in
node_modules, similar to what Webpack supports.
This option (abbreviated -p) takes an identifier prefix to remove from the
beginning of all variable, mixin, and function names when they’re migrated.
Members that don’t start with this prefix will remain unchanged.
The @import rule put all top-level members in one global scope, so when it
was the standard way of loading stylesheets, everyone was incentivized to add
prefixes to all their member names to avoid accidentally redefining some other
stylesheet’s. The module system solves this problem, so it’s useful to
automatically strip those old prefixes now that they’re unnecessary.
$ cat style.scss
@import "theme";
@mixin app-inverted {
color: $app-bg-color;
background-color: $app-color;
$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss
$ cat style.scss
@import "theme";
@mixin inverted {
color: theme.$bg-color;
background-color: theme.$color;
When you pass this option, the migrator will also generate an import-only
stylesheet that forwards all the members with the prefix added back, to
preserve backwards-compatibility for users who were importing the library.
This option may be passed multiple times, or with multiple values separated by
commas. Each prefix will be removed from any members that have it. If a member
matches multiple prefixes, the longest matching prefix will be removed.
This option tells the migrator which members to forward using the @forward
rule. It supports the following settings:
none (the default) doesn’t forward any members.
all forwards all members except those that started with - or _ in the
original stylesheet, since that was commonly used to mark a package-private
member before the module system was introduced.
prefixed forwards only members that begin with the prefix passed to the
--remove-prefix option. This option may only be used in conjunction with
the --remove-prefix option.
All files that are passed explicitly on the command line will forward members
that are transitively loaded by those files using the @import rule. Files
loaded using the --migrate-deps option will not forward any new members.
This option is particularly useful when migrating a Sass library, because it
ensures that users of that library will still be able to access all the members
it defines.
$ cat _index.scss
@import "theme";
@import "typography";
@import "components";
$ sass-migrator --migrate-deps module --forward=all style.scss
$ cat _index.scss
@forward "theme";
@forward "typography";
@forward "components";
This migration allows you to easily change the namespaces of the @use
rules in a stylesheet. This is useful if the namespaces that the module migrator
generates to resolve conflicts are non-ideal, or if you don’t want to use the
default namespace that Sass determines based on the rule’s URL.
You can tell the migrator which namespace(s) you want it to change by passing
expressions to the --rename option.
These expressions are of the form <old-namespace> to <new-namespace> or
url <rule-url> to <new-namespace>. In these expressions, <old-namespace> and
<rule-url> are regular expressions which match against the entirety of the
existing namespace or the @use rule’s URL, respectively.
For simple use cases, this just looks like --rename 'old to new', which would
rename a @use rule with the namespace old to instead be new.
However, you can also do this to accomplish more complicated renames. For
instance, say that you previously had a stylesheet that looked like this:
@import 'components/button/lib/mixins';
@import 'components/input/lib/mixins';
@import 'components/table/lib/mixins';
Since all of these URLs would have the default namespace mixins when migrated
to @use rules, the module migrator may end up generating something like this:
@use 'components/button/lib/mixins' as button-lib-mixins;
@use 'components/input/lib/mixins' as input-lib-mixins;
@use 'components/table/lib/mixins' as table-lib-mixins;
This is valid code since the namespaces don’t conflict, but they’re way more
complicated than they need to be. The relevant part of the URL is the component
name, so we can use the namespace migrator to extract that part out.
If we run the namespace migrator with
--rename 'url components/(\w+)/lib/mixins to \1', we’ll end up with:
@use 'components/button/lib/mixins' as button;
@use 'components/input/lib/mixins' as input;
@use 'components/table/lib/mixins' as table;
The rename script here says to find all of the @use rules whose URLs look like
components/(\w+)/lib/mixins (\w+ in a regular expression means to match any
word of one or more characters). The \1 in the output clause means to
substitute in the contents of the first set of parentheses in the regular
expression (called a group).
If you wish to apply multiple renames, you can pass the --rename option
multiple times, or separate them with a semicolon or a line break. Only the
first rename that applies to a given rule will be used, so you could pass
something like --rename 'a to b; b to a' to swap the namespaces a and b.
By default, if two or more @use rules have the same namespace after the
migration, the migrator will fail, and no changes will be made.
In this case, you’ll usually want to adjust your --rename script to avoid
creating conflicts, but if you’d prefer to force the migration, you can instead
pass --force.
With --force, if any conflicts are encountered, the first @use rule will
get its preferred namespace, while subsequent @use rules with the same
preferred namespace will instead have a numerical suffix added to them.
