Fixing Sass @import deprecation warnings

Using Sass >= 1.80 and wanting to shush those @import deprecation notices with minimal effort?

There was a nice clear notice , with a decent explainer.

But you want a quick 1-2-3, so keep reading 🙃

It should take you minutes, not hours.

Do the upgrade

They made a lovely cli tool to help us out -> https://sass-lang.com/documentation/cli/migrator/

It should help us do exactly what we need to do, and it's got nice documentation if you need further options or details.

Install the tool

As per their instructions, there are lots of ways to install.

Our skittish Drupallers currently recommend to do something like this:

// Hop into your ddev container, if using
ddev ssh

// Install carefully
npm install -g sass-migrator --ignore-scripts

Run the tool

We need to run the module migration, which handles the @import statement changes (and a couple of other necessary bits - read the docs if you're concerned)

For each top level .scss file, we're going to run a command like this:

sass-migrator module ./path/to/style.scss -dv

We're using the d flag to --migrate-deps - which will help ensure that child stylesheets get upgraded too.

We're also using the v flag for --verbose - to make sure we get decent output if something goes wonky.

So a real-world example for a Drupal theme looked like this: 

sass-migrator module ./webroot/themes/custom/cmx/sass/base/base.scss -dv

And I used PHPStorm to make the various duplications for the different top-level scss files across my theme's directories, paste a big pile of commands all at the same time.

You could probably make a nice script to find them all and run magically 🤔

Things that don't work

Susy

You'll get errors for susy/susy, which the tool can't upgrade (and it shouldn't be!).

1. Comment out the @import 'susy/susy'; line
2. Run the migrations
3. Go back and reinstate, changing @import to @use

⚠️ Important: you can't make the @use change before you run the migration, as the tool will assume the file has already been upgraded!

Check your changes

Can’t stress this enough. Make sure you’re getting what you expect and that it all looks good!

Compile

Run your compile action (gulp, watch, sass or whatever) and check that it runs happily. Hopefully all is good and there aren’t any deprecation logs anymore.

If there are some, go back and run the migration on those affected files.

Git diff your compiled css

The changes should be few and trivial, though that depends on your project!

Take a look!

Check out your website locally or on staging, make sure it’s tickety boo.