The Module System is Launched

Posted 2 October 2019 by Natalie Weizenbaum

The Sass team has known for years that the @import rule, one of the earliest additions to Sass, wasn’t as good as we wanted it. It caused a litany of problems for our users:

We also knew that any replacement we wanted to introduce would have to be designed and developed with the utmost care to ensure it would provide a rock-solid foundation for the future of Sass development. Over the past few years, we’ve discussed, designed, and developed a brand-new module system that solves these problems and more, and today we’re excited to announce that it’s available in Dart Sass 1.23.0.

Please note that the module system is fully backwards-compatible. No existing features have been removed or deprecated, and your current Sass stylesheets will keep working just as they always have. We designed the module system to be fully interoperable with @import to make it easy for stylesheet authors to migrate to it incrementally. We do plan to eventually get rid of @import, but not until long after everyone’s had a chance to migrate.

@use, the Heart of the Module System permalink@use, the Heart of the Module System

The @use rule is the primary replacement for @import: it makes CSS, variables, mixins, and functions from another stylesheet accessible in the current stylesheet. By default, variables, mixins, and functions are available in a namespace based on the basename of the URL.

@use "bootstrap";

.element {
  background-color: bootstrap.$body-bg;
  @include bootstrap.float-left;
}

In addition to namespacing, there are a few important differences between @use and @import:

Note that placeholder selectors are not namespaced, but they do respect privacy.

Controlling Namespaces permalinkControlling Namespaces

Although a @use rule’s default namespace is determined by the basename of its URL, it can also be set explicitly using as.

@use "bootstrap" as b;

.element {
  @include b.float-left;
}

The special construct as * can also be used to include everything in the top-level namespace. Note that if multiple modules expose members with the same name and are used with as *, Sass will produce an error.

@use "bootstrap" as *;

.element {
  @include float-left;
}

Configuring Libraries permalinkConfiguring Libraries

With @import, libraries are often configured by setting global variables that override !default variables defined by those libraries. Because variables are no longer global with @use, it supports a more explicit way of configuring libraries: the with clause.

// bootstrap.scss
$paragraph-margin-bottom: 1rem !default;

p {
  margin-top: 0;
  margin-bottom: $paragraph-margin-bottom;
}
 
@use "bootstrap" with (
  $paragraph-margin-bottom: 1.2rem
);

This sets bootstrap’s $paragraph-margin-bottom variable to 1.2rem before evaluating it. The with clause only allows variables defined in (or forwarded by) the module being imported, and only if they’re defined with !default, so users are protected against typos.

@forward, for Library Authors permalink@forward, for Library Authors

The @forward rule includes another module’s variables, mixins, and functions as part of the API exposed by the current module, without making them visible to code within the current module. It allows library authors to be able to split up their library among many different source files without sacrificing locality within those files. Unlike @use, forward doesn’t add any namespaces to names.

// bootstrap.scss
@forward "functions";
@forward "variables";
@forward "mixins";

Visibility Controls permalinkVisibility Controls

A @forward rule can choose to show only specific names:

@forward "functions" show color-yiq;

It can also hide names that are intended to be library-private:

@forward "functions" hide assert-ascending;

Extra Prefixing permalinkExtra Prefixing

If you forward a child module through an all-in-one module, you may want to add some manual namespacing to that module. You can do what with the as clause, which adds a prefix to every member name that’s forwarded:

// material/_index.scss
@forward "theme" as theme-*;

This way users can use the all-in-one module with well-scoped names for theme variables:

@use "material" with ($theme-primary: blue);

or they can use the child module with simpler names:

@use "material/theme" with ($primary: blue);

Built-In Modules permalinkBuilt-In Modules

The new module system also adds built-in modules (sass:math, sass:color, sass:string, sass:list, sass:map, sass:selector, and sass:meta) to hold all the existing built-in Sass functions. Because these modules will (typically) be imported with a namespace, it’s now much easier to use Sass functions without running into conflicts with plain CSS functions.

This in turn makes it much safer for Sass to add new functions. We expect to add a number of convenience functions to these modules in the future.

Renamed Functions permalinkRenamed Functions

Some functions have different names in the built-in modules than they did as global functions. Built-in functions that already had manual namespaces, like map-get(), have those namespaces removed in the built-in modules so you can just write map.get(). Similarly, adjust-color(), scale-color(), and change-color() are now color.adjust(), color.scale(), and color.change().

We’ve also taken this opportunity to change a couple confusing old function names. unitless() is now math.is-unitless(), and comparable() is now math.compatible().

Removed Functions permalinkRemoved Functions

Sass’s shorthand color functions lighten(), darken(), saturate(), desaturate(), opacify(), fade-in(), transparentize(), and fade-out() all had very unintuitive behavior. Rather than scaling their associated attributes fluidly, they just incremented them by a static amount, so that lighten($color, 20%) would return white for a color with 85% lightness rather than returning a color with 88% lightness (20% closer to full white).

To help set us on the path towards fixing this, these functions (along with adjust-hue()) aren’t included in the new built-in modules. You can still get the same effect by calling color.adjust()—for example, lighten($color, $amount) is equivalent to color.adjust($color, $lightness: $amount)—but we recommend trying to use color.scale() instead if possible because of how much more intuitive it is.

At some point in the future, we plan to add color.lighten() and similar functions as shorthands for color.scale().

meta.load-css() permalinkmeta.load-css()

The new module system comes with a new built-in mixin, meta.load-css($url, $with: ()). This mixin dynamically loads the module with the given URL and includes its CSS (although its functions, variables, and mixins are not made available). This is a replacement for nested imports, and it helps address some use-cases of dynamic imports without many of the problems that would arise if new members could be loaded dynamically.

@import Compatibility permalink@import Compatibility

The Sass ecosystem won’t switch to @use overnight, so in the meantime it needs to interoperate well with @import. This is supported in both directions:

In order to allow libraries to maintain their existing @import-oriented API, with explicit namespacing where necessary, this proposal also adds support for files that are only visible to @import, not to @use. They’re written "file.import.scss", and imported when the user writes @import "file".

Automatic Migration permalinkAutomatic Migration

Concurrent with the launch of the new module system, we’re launching a new automated Sass migrator. This tool makes it easy to migrate most stylesheets to use the new module system automatically. Follow the instructions on the Sass website to install it, then run it on your application:

$ sass-migrator module --migrate-deps <path/to/style.scss>

The --migrate-deps flag tells the migrator to migrate not only the file you pass, but anything it imports as well. The migrator will automatically pick up files imported through Webpack’s node_modules syntax, but you can also pass explicit load paths with the --load-path flag.

If you want the migrator to tell you what changes it would make without actually making them, pass both the --dry-run flag and the --verbose flag to tell it to just print out the changes it would make without saving them to disk.

Migrating a Library permalinkMigrating a Library

If you want to migrate a Sass library that’s meant for downstream users to load and use, run:

$ sass-migrator module --migrate-deps --forward=all <path/to/index.scss>

The --forward flag tells the migrator to add @forward rules so that users can still load all the mixins, variables, and functions your library defines with a single @use.

If you added a manual namespace to your library to avoid name conflicts, the migrator will remove it for you if you pass the --remove-prefix flag. You can even choose to only forward members that originally had that prefix by passing --forward=prefixed.

Filing Issues permalinkFiling Issues

The migration tool is brand new, so it may still have some rough edges. If you run into any problems, please don’t hesitate to file an issue on GitHub!

Try It Now! permalinkTry It Now!

The module system is available as part of Dart Sass 1.23.0. You can install it right now using:

$ npm install -g sass

Alternately, check out the installation page for all the different ways it can be installed!

Future Plans permalinkFuture Plans

The Sass team wants to allow for a large amount of time when @use and @import can coexist, to help the ecosystem smoothly migrate to the new system. However, doing away with @import entirely is the ultimate goal for simplicity, performance, and CSS compatibility. As such, we plan to gradually turn down support for @import on the following timeline:

This means that there will be at least two full years when @import and @use are both usable at once, and likely closer to three years in practice.