One quick way to get ready for Carbon v11

Expanding on our April announcement that Carbon will be moving to Dart Sass from Node Sass, we wanted to take a closer look at how projects using carbon-components can prepare for this change today, before v11 is released.

Transition from node-sass to sass

For those unfamiliar with recent changes in the sass ecosystem, node-sass is a very popular wrapper around the LibSass implementation of sass that has been deprecated. sass is now the recommended package and is built atop the dart-sass implementation.

Beginning in v11, Carbon will require the use of sass. To migrate, it typically will require just one step — swap the node-sass dependency for sass. In most projects it’s included as a devDependency.

yarn remove node-sass
yarn add sass --dev
// or with npm:
npm uninstall node-sass
npm install sass --save-dev

The Sass team has outlined further migration information including a list of known compatibility issues and the potential fixes available.

Handling multiple instances of node-sass

If your project is a collection of multiple packages, perhaps organized as a monorepo, you’ll want to replace all usages of node-sass with sass. It may be helpful to search your dependency tree for node-sass to gather a list of sub dependencies or packages you may need to update or reconfigure.

yarn why node-sass
// or with npm:
npm ls node-sass

The sass package exports the same API as node-sass and is intended to be an in-place update without any required changes. If you’re using webpack, sass-loader should default to using the sass implementation if you remove the implementation key from your options config. In some cases you may still need to explicitly require the correct implementation.

{
  implementation: require('sass')
}

Confirm your project is using the correct implementation

One way to confirm that your project is probably using the correct implementation is to run a small smoke test using import-only files. With this approach you can add a couple test files, tmp.import.scss and tmp.scss. If you import this in your central entrypoint file, node-sass will use tmp.scss while sass will use tmp.import.scss.

// index.scss
@import './tmp';
// _tmp.scss
@debug '_tmp.scss was processed, likely using node-sass';
// _tmp.import.scss
@debug '_tmp.import.scss was processed, likely via sass';

After running a build, you should see output on your console indicating which file was processed.

Resolve common problems with the Sass Migrator

Depending on the sass language features your project is using, you may encounter deprecation warnings or other messages after swapping out node-sass for sass. These are only warnings and should not impact the success of your build.

One very common deprecation warning that was present in the Carbon codebase itself was the deprecation of using a slash / for division. Thankfully, the Sass team provides a sass-migrator CLI to assist with upgrading a codebase to new language features. We appreciated being able to run the division migration to update our files automatically with the new math.div function intended to replace slash for division.

sass-migrator division path/to/styles/*.scss

For full details, check out the documentation for sass-migrator.

Include node_modules as a load path

In v11, you will need to configure Sass to be able to find packages from your node_modules folder. To do this, use the includePaths option and set its value to an array of load paths where Sass should look to find node_modules folders.

For most projects, this configuration will look like this:

{ 
  "includePaths": ["node_modules"] 
}

If you are using the Sass CLI directly, use the --load-path flag:

$ sass --load-path=node_modules style.scss style.css

In some projects, particularly those organized as a monorepo, the build path may not be colocated with node_modules. In this case, it may be helpful to use a javascript-based config file so that multiple node_modules paths can be resolved dynamically.

const path = require('path');
module.exports = {
 includePaths: [
  path.resolve(__dirname, '../../node_modules'),
  path.resolve(__dirname, '../../../../node_modules'),
 ],
};

Note that this config is an array value, and earlier load paths will take precedence over later ones. Read more about Sass load paths in the documentation.

A note on Sass Modules

The most prominent feature available through the sass dependency is the new Sass module system. Beginning in v11, Carbon will provide a new @carbon/styles package built using Sass Modules. This does not mean that your codebase needs to migrate right now to use Sass Modules. The Carbon styles will continue to work using @import for now with some tweaks if your styles are using Carbon tokens, functions, or mixins. We’ll provide more in-depth information on this as we near the v11 release through new migration documentation.

There are numerous benefits to using Sass Modules including smaller bundle size and increased build performance. If you’re interested to learn more and would like to get a jump start on it, there is a module migration available through the sass-migrator.

Continuing the path towards v11

These steps should begin to prep your project for the changes coming in the next major version of Carbon.

Overall these changes should be pretty uneventful, but if you encounter issues moving off of node-sass please contribute feedback in our Github discussion. So far we’ve seen that most issues are likely be related to config options and may not be easily reproducible outside of your project environment. It’s always helpful to narrow down your issue into a reproducible codesandbox example when reporting problems.

As portions of our v11 work stream are completed we’ll be publishing more migration documentation and posts like these to communicate what’s coming. Be on the lookout for our next beta release soon!

Taylor Jones is a Software Engineer based out of Austin, TX working on the Carbon Design System. The above article is personal and does not necessarily represent IBM’s positions, strategies, or opinions.

Questions or comments about Carbon? Reach out at carbon@us.ibm.com or tweet us @_carbondesign.