Narcoleptic Possum Mob

    sass-versioning

    0.4.4 • Public • Published

    Build Status

    Sass-versioning

    NPM

    Version your sass modules and test them at compile time. Inspired by Salesforces Sass deprecate this package enables you to combine individually versioned sass partials with interdependencies and check for conflicts before you generate the CSS.

    Sass error examples

    Content


    Usage

    Sass-versioning replies on semantically versioned modules. According to semver a major version will break backwards compatibility while minor and patch versions keep backwards compatibility intact so this script will throw errors only on major version mismatches and when a module can't be found.

    Example

    If you have multiple versioned Sass modules and need to defined dependencies amongst them, this is for you.

    Imagine you have a couple modules:

    core v1.0.0

    @mixin mixins {
    	//some awesome css in a mixin we called "mixins" because #namingishard
    }

    core v2.0.0

    @mixin core {
    	//some awesome css in a mixin we renamed to "core"
    }

    grid v1.1.0

    @import "core";
    
    @include mixins(); //we clearly need version 1.0.0 of the core module with the old named mixin
                       //this will fail if you only @import core v2.0.0

    accordion v2.0.0

    @include core(); //this module has been updated to digest the new version of core 2.0.0
                     //this will fail if you only @import core v1.0.0

    Each of these come with interdependencies and we need to check for conflicts. Like if grid was dependent on core v1.0.0 but only v2.0.0 was imported or on an entirely different module that we don’t even have in our imports. To see more examples check out the ./test/ folder.

    To make sure this works, we need to register each module and at the bottom of all imports check for conflicts and throw errors on conflicts.

    Register

    To register a module you need three parameter and call the versioning-add mixin. You do that in each module that can possibly be dependent upon.

    $name: "accordion";   //the name of this module
    $version: "1.0.0";    //the version of this module
                          //all dependencies of that module
                          //this module depends on a module named "core" at version "2.0.0"
                          //this module depends on a module named "grid" at version "1.0.0"
    $dependencies: (
    	("core", "2.0.0"),
    	("grid", "1.0.0"),
    );
    
    @include versioning-add( $name, $version, $dependencies ); //call the mixin to register your module
    
    //add some awesome Sass here

    If your module has no dependencies you can simply leave the $dependencies empty. That would look like this:

    $name: "core";
    $version: "2.0.0";
    $dependencies: ();  //no dependencies
    
    @include versioning-add( $name, $version, $dependencies );
    
    //add some awesome Sass here

    Removing a dependency

    Sometimes you may want to remove a dependency before checking for conflicts as, while the module is a dependency, it may not come with a sass file.

    @include versioning-remove( 'grid' );

    This will remove the grid module from all dependencies. Make sure you run versioning-remove before versioning-check() though.

    Check for conflicts

    When you include all those modules you now need to check for conflicts with the versioning-check() mixin. Make sure you call this at the bottom after all includes.

    @import "module1";
    @import "module2";
    @import "module3";
    
    @include versioning-check();

    This mixin will throw a descriptive @error if it finds a conflicts.

    $ sass test2.scss test.css
    Error: The module "grid" requires "core" v2.0.1. But "core" v2.0.0 included.
            on line 510 of ../dist/index.scss, in "versioning-check"
            from line 63 of test2.scss
    
    $ sass test3.scss test.css
    Error: The module "grid" requires "core" v1.0.0. But "core" v2.0.0 included.
            on line 510 of ../dist/index.scss, in "versioning-check"
            from line 63 of test3.scss
    
    $ sass test4.scss test.css
    Error: The module "grid" requires "core" v2.1.0. But "core" v2.0.0 included.
            on line 510 of ../dist/index.scss, in "versioning-check"
            from line 63 of test4.scss
    
    $ sass test5.scss test.css
    Error: The module "grid" requires "core" v3.0.0. But "core" v2.0.0 included.
            on line 510 of ../dist/index.scss, in "versioning-check"
            from line 63 of test5.scss
    
    $ sass test6.scss test.css
    Error: The module "grid" requires "buttons" v1.0.0. But the dependency is missing entirely
            on line 516 of ../dist/index.scss, in "versioning-check"
            from line 63 of test6.scss

    back to top


    Build

    We got three npm scripts you can run:

    • concat
    • generate-doc
    • test
    • watch

    concat

    Deletes the ./dist/ folder, creates it again (to make sure we always have the latest in the folder) and concatenates all files from ./src/ into ./dist/index.scss.

    generate-doc

    Using Sassdoc this task generates the documentation for our Sass into the ./sassdoc/ folder.

    test

    Will run the test described below.

    watch

    Our watch checks for changes inside the ./src/ folder and runs the concat, generate-doc and test tasks.

    back to top


    Test

    To test run npm test in the project folder. The test script will run over each *.scss file inside the ./test/ folder. Each of those files has a comment at the very first line of the file that looks like this:

    // expected: [expected error message]
    
    .some-css {} //etc

    The test script will compare the error message found here [expected error message] against what sass outputs.

    back to top


    Release History

    • v0.4.4 - Updated dependencies
    • v0.4.3 - Updated dependencies
    • v0.4.2 - Updated dependencies
    • v0.4.1 - Updated dependencies
    • v0.4.0 - Move to sass and remove node-sass as dev dependency, updated dependencies
    • v0.3.0 - Added versioning-remove
    • v0.2.2 - Renamed to sass partial naming convention
    • v0.2.1 - Fixed package.json files array
    • v0.2.0 - Added eyeglass support, moved to @HugoGiraudel excellent sass-semver, added more docs
    • v0.1.2 - Tweaked code credit
    • v0.1.1 - Added to documentation
    • v0.1.0 - Initial starting point

    back to top


    License

    Copyright (c) Dominik Wilkowski. Licensed under the GPL-3.0.

    back to top

    };

    Install

    npm i sass-versioning

    DownloadsWeekly Downloads

    44

    Version

    0.4.4

    License

    GPL-3.0

    Unpacked Size

    62.4 kB

    Total Files

    4

    Last publish

    Collaborators

    • dominikwilkowski