Write Sass plugins like a pro

10 things to consider when writing Sass plugins for public or shared use

Be aware of naming conventions

There are conventions for writing code, use them! Even if it’s difficult to adapt. Nothing is uglier then mixed conventions. Sass is an hyphenated language.

$this_is_a_variable //wrong
$thisIsAVariable //wrong
$this-is-a-variable //right

Prefix private data (mixins, variables and functions that are only used internally) using an underscore, that’s also common practice in other languages. This is usable because the IDE of your users will not suggest an auto completion for private stuff and this prevents naming conflicts with other libraries.

$_variable //private
$variable //public
@function _stuff() {..} //private
@function stuff() {..} //public

Use the !default flag for changeable settings. Variables flagged with !default will not overwrite previously defined variables.

$change-this: 16px !default;

Harry Roberts did a nice job in collecting most conventions for CSS at cssguideline.es.

Consider using a prefix for your plugin

As functions and mixins are scoped globally they might lead to naming conflicts. I highly recommend to use a prefix for your functions to avoid them! I know it’s ugly, but you want people to use your plugin without having trouble, right?

For my plugins I am splitting code into private and public parts. The private part is prefixed and underscored. It will probably never lead to any naming conflicts. The public part includes the private part and adds nice, “human readable” names.

Make sure everything will be used like expected

You, as the author of your plugin, will probably never ever use it the wrong way. You’ll never enter wrong type of parameter, cause you know what your function expects. You’ll never forget to import a file, cause you know what happens if you do. But others will! Other people will forget those things, they will do it wrong. So check for dependencies and validate your parameters. Make use of functions like variable-exists() or function-exists().

As an example: you can check if your _settings.scss was imported using variable-exists().

//plugin.css
@if variable-exists(settings-imported) == false {
    @error 'You need to import settings first!;
}
//_settings.scss
$settings-imported: true;

Do one thing and one thing well

Don’t bloat your plugin. Don’t fulfill more than one need. Don’t force users to use more than they want. You simply don’t know if they have the same needs like you. So if you notice that your plugin does more than one thing: split it into different repositories. Suggest people to use both but don’t force them.

Document everything

Everything needs to be documented! You can use docblock comments in Sass as well!

/** 
 * write your description here
 * ---
 * @access private
 * ---
 * @param {string} $test — just a test
 */

The best thing about it: when you are done you can generate a whole online documentation automatically! Have a look at awesome SassDoc.

Respect semantical versioning

Use git tags to provide new releases of your plugin, but don’t just use nice numbers. Versions have a meaning and they will tell others about the changes you’ve made. Read more about SemVer.

Test it

Test your plugin often! Test every function, test every mixin. Tell people which browser you support and test those! Most users will never get back to your plugin after they’ve got an error.

I recommend using Bootcamp for unit testing your Sass. After setting it up you can combine it with a Continuous Integration Tool like TravisCi, which is free for open source repos.

Let a task manager do the shit for you

Use grunt or gulp to run your tasks! You’ll save a lot of time. Embed a task manager into your project. This will help others to make changes in your project as well. Run automated Bootcamp tests with grunt. Concatenate your partials into a single file, that makes it easier and faster to use it in a project.

Publish on Github

Simply forget about other platforms: Github is the big player when it comes to open source projects. It offers a lot of useful features like pull requests, traffic and a lot more. It’s the most important social media platform for developers.

Register at Bower

Bower is the easiest way for frontend developers to include a plugin into a project and maintain their updates. Register your plugin into bower registry so users can just use a simple command line to get your plugin. Make everything as easy as possible!

Besides bower as a package manger there are some online indexes for Sass plugins like Sache.in.

Make it public

Your plugin is useless if nobody knows about it. Use Twitter, Facebook and Google+ to spread your new awesome plugin. Write an article explaining the functionality. Don’t be afraid, just tell the world about your code. It’s open source, nobody pays for it and everybody may change it! The idea counts.

This is just what I’ve learned writing Sass plugins so far. Do you have any recommendations? Do you disagree with something I wrote?

Want to keep updated about my stuff? Just follow me on Twitter.