HTML & CSS
Article

Using Sass’s @error, @warn, and @debug Directives

By James Steinbach

Feedback methods are essential in any programming language. In JavaScript, you’ve probably used console.log() or maybe alert(). In PHP, you can use var_dump() or print_r(). In Ruby, you may use debug or inspect. All these functions allow you to debug any value and find out what your code is doing at any point in the logic where you need help.

Sass has three directives for providing feedback to developers. They are @error, @warn, and @debug. In this post, we’ll look at how to use these directives, what use cases they’re best suited for, and what kind of feedback they can provide for other developers who use our code.

Basic Syntax and Use

All three of these directives follow the same syntax:

@directive "String of text to output.";

Well, that’s not entirely true. The three directives expect anything, not necessarily a string. This means you can warn, throw, or debug a map, a list, a number, a string — basically anything you want. However, as we often use these directives to give some context on the problem, we’ll usually pass a string that describes the situation.

If you need to interpolate a variable’s value in that string, you can do so using the standard Sass interpolation (#{$variable}) and the value will be printed in the string. With this method, you can tell a developer both the name of the variable and its current value:

@error "Sorry, but `#{$variable}` is not a valid value for $variable.";

Note that the ticks (`) around the interpolation are not required. You may want to include them because they give the developer an obvious start/stop point for the variable’s contents.

If a developer makes a mistake when using your Sass code, these directives will send the specified message to the compiler and the compiler will show that message to the developer. For example, GUI apps (like CodeKit) will show a system notification with the error. Certain Grunt and Gulp notification packages can do that as well.

If a developer is compiling with the command line (Sass, Compass, Grunt, or Gulp), the message will likely end up in their console (Terminal, iTerm2, Putty, etc). If you’re writing Sass online with Sassmeister or Codepen, you’ll only get limited feedback, but you may get an inline notification in your editor or text in the output window.

Now that we know how to write @error, @warn, and @debug messages and where they’ll appear for the developer, let’s look at the difference between these directives and the best uses for each one.

Stop Everything – The @error Directive

Sass’s @error directive stops the Sass compiler completely and sends its string of text to the compiler’s output as a fatal error. Use this directive when you need to send a message that stops the developer immediately and forces them to correct their mistake right away. This is ideal for letting a developer know they’ve done something wrong or entered a value that’s entirely incompatible. Sass will include the line number with any fatal error, including @error output. The @error directive is ideal for validating arguments within a mixin or function.

Note: If your compiler is older than Sass 3.4 or LibSass 3.1, @error is not available. You can use this log() function to emulate @error in older Sass versions.

As an example, if you’ve written a function that relies on a certain input format for its calculations, you can validate the input and use @error to stop the compiler and alert the developer that they’ve made a mistake that can’t be overlooked. If you’ve written a function that relies on a key/value pair from a map, @error can make sure that the key that’s called from the map actually exists.

This Sass color management tool uses @error to ensure that the developer only uses a color name that’s a valid CSS color name or a key from a related map:

Map:

$colors: (
  brand-red: #c0392b,
  brand-blue: #2980b9,
  text-gray: #2c3e50,
  text-silver: #bdc3c7
);

Function (simplified for the sake of brievity):

@function color-variation($color) {
  @if map-has-key($colors, $color) {
    @return map-get($colors, $color);
  }
  
  @error "Invalid color name: `#{$color}`.";
}

Usage:

.element {
  color: color-variation(brand-orange);
}

Output:

>> Invalid color name: `brand-orange`.
>>   Line 9  Column 7  sass/test.scss

In this example, if the developer tries calling the color-variation() function with a string that’s neither a valid CSS color nor a key from the $colors map, there’s nothing Sass can do to output a valid color. Using @error gives the developer specific, actionable feedback.

Don’t Miss This – The @warn Directive

The @warn directive is considerably less severe than @error. It sends its message to the compiler for the developer to read, but it allows the compiler to finish its job and write all the CSS. While @error is good for correcting an error that breaks a function or mixin entirely, @warn is better suited for deprecation notices, or suggesting a developer follow certain best practices.

Note: Sass developers who use the --quiet flag when they compile will not see @warn output. If the developer absolutely needs to see the feedback your Sass is sending, rely on @error. It’s rare for @warn to be turned off, but it is possible.

Sass will also include a line number with @warn output to help the developer find and improve any code that needs to be edited. For example, you may have a library full of mixins, and you plan to deprecate several of the mixins in a future release. One way to help your developers prepare for that change is to @warn them about the upcoming deprecation:

// No one should ever prefix border-radius properties ;)
// so let's deprecate this from our imaginary library:

@mixin border-radius($radius) {
  @warn "The `border-radius()` mixin will be deprecated in version 2.0.";

  -webkit-border-radius: $radius;
  -moz-border-radius: $radius;
  -ms-border-radius: $radius;
  -o-border-radius: $radius;
  border-radius: $radius;
}

Output:

WARNING: The `border-radius()` mixin will be deprecated in version 2.0.
  on line 2 of sass/test.scss
  from line 21 of sass/test.scss

You can see this in action in this deprecation partial from Bourbon Sass.

Another good use case for @warn is enforcing team code standards. You might write a function that can successfully handle input in both pixels or rem units, but you might prefer everyone on your team uses rems. Here’s an example of @warn to help your coworkers follow that standard:

@function do-math($input) {
  @if unit($input) == "px" {
    @warn "Please remember to use rem values in the `do-math()` function.";
    // do px math and @return a value to prevent the function from going any further
  }
  
  // do rem math and @return a value
}

Output:

WARNING: Please remember to use rem values in the `do-math()` function.
  on line 3 of sass/test.scss
  from line 12 of sass/test.scss

If You Were Curious – The @debug Directive

Sass’s @debug directive is the least intrusive of all three feedback directives. It prints the value of whatever Sass expression it contains (variable, math, etc.) to the console for the developer. It’s not entirely useful in open source or team libraries. Rather, @debug is ideal for personal debugging work. If you’re in a complex bit of math and need to know what one of your variables contains at the moment, use @debug to find out.

Usage:

$color-blue: #1c94c6;
$font-sizes: sm, p, bq, heading, hero;
$colors: (
  brand-red: #c0392b,
  brand-blue: #2980b9,
  text-gray: #2c3e50,
  text-silver: #bdc3c7
);

.element {
  @debug $color-blue; // single value
  @debug $font-sizes; // list
  @debug $colors; // map
  @debug 4em * 3; // math expression
  @debug "My very own string just because."; // string
}

Output:

sass/test.scss:5: DEBUG: #1c94c6
sass/test.scss:6: DEBUG: sm, p, bq, heading, hero
sass/test.scss:7: DEBUG: (brand-red: #c0392b, brand-blue: #2980b9, text-gray: #2c3e50, text-silver: #bdc3c7)
sass/test.scss:8: DEBUG: 12em
sass/test.scss:9: DEBUG: My very own string just because.

Conclusion

Programming in a black hole without feedback would be awful. Fortunately, Sass has multiple directives that can send feedback to the compiler to help developers avoid mistakes, maintain standards, and troubleshoot advanced logic. You can use @error, @warn, and @debug to provide time-saving feedback for yourself and for any others who use your code.

Do you have any creative uses for these directives? Share them in the comments!

No Reader comments

Recommended

Learn Coding Online
Learn Web Development

Start learning web development and design for free with SitePoint Premium!

Get the latest in Front-end, once a week, for free.