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.