Uswds: [Sass] Easier use with node-sass include paths

[shawnbot]

Currently, both of options for including the Sass sources are kind of ugly. You have to do one of the following:

1. Reference the all.scss via its full path, or path relative to the including Sass file, as in cg-style:

scss @import '../../node_modules/uswds/src/stylesheets/all.scss';

1. Or you can add a path to node-sass's includePaths option, a la:

js sass.render(..., { includePaths: 'node_modules/uswds/src/stylesheets' });

Which is nicer, but it means that you have to ambiguously refer to the all file like this:

scss @import 'all'; // via uswds

Which will not work as expected if you have your own all.scss locally.

Description

I really like the way that Bourbon and Neat do it, which is to export an includePaths array from the top-level JS module, and then you can load them in Sass via their formal names:

// sass config
{
  includePaths: [/* your local include paths here */]
    .concat(require('bourbon').includePaths))
    .concat(require('bourbon-neat').includePaths))
}

@import 'bourbon';
@import 'neat';

It would be great if WDS followed this pattern, so users could do the same:

// sass config
{
  includePaths: [/* your local include paths here */]
    .concat(require('uswds').includePaths))
    .concat(require('bourbon').includePaths))
    .concat(require('bourbon-neat').includePaths))
}

@import 'uswds';
@import 'bourbon';
@import 'neat';

Alternatively, as Bourbon and Neat's docs suggest, we could consider offering some examples for using WDS with Eyeglass.

[shawnbot]

For reference, I'm looking at what it would take to build a Yeoman generator that incorporated Bourbon, Neat and WDS and built them with the 18F Felt recipe. My sass.config.js looks like this:

var includePaths = [
];

['bourbon', 'bourbon-neat'].forEach(mod => {
  try {
    mod = require(mod);
  } catch (error) {
    return;
  }
  includePaths = includePaths.concat(mod.includePaths);
});

module.exports = {
  includePaths: includePaths
};

If we followed the Bourbon/Neat pattern, we could just add uswds to the list of modules whose includePaths are concatenated. The list of sass modules could even be moved to package.json:

{
  "sass": {
    "include": ["bourbon", "bourbon-neat", "uswds"]
  }
}

// sass.config.js
var includePath = [];
const pkg = require('package.json');
pkg.sass.include.forEach(mod => {
  includePath = includePath.concat(require(mod).includePaths || []);
});

[shawnbot]

Another thing that I came across when trying to simplify the gulp sass task is that we might be able to get away without the whole copy-vendor-sass rigamarole if we don't need to include Bourbon, Neat, and normalize.css in the release build. @msecret, can you speak to that?

[msecret]

@shawnbot I'm not sure I'm following. Doesn't the release need to include bourbon, neat and normalize? Or are you saying when you use the standards, you use the include paths so they aren't in the npm package?

[shawnbot]

Ah, well if the standards needs to include it (I wasn't sure if it did), then it would be preferable if you the bourbon and neat include paths could be included in the require('uswds').includePaths so that I could just use those instead of manually including Bourbon and Neat directly. Copying the Bourbon and Neat files over as part of the npm install process would be unnecessary in that case. Or maybe they could be symlinked instead, so that folks using other Bourbon or Neat mixins (via node-sass, at least) would be referencing the same files?

[lukad03]

@shawnbot Using includePaths for the USWDS only, I'm able to reference functions unique to Bourbon and Neat without needing to install those as well. The main issue then is the naming of the all file in the USWDS node package. Currently I'm using includePaths and creating a vendor directory with a _uswds.scss file in it dedicated to importing all. Though not ideal, this helps avoid import loops on the generically named all file and provides context for importing the USWDS.

[shawnbot]

@lukad03 be on the lookout for the next release, which should solve this problem! See #1530 for more info, and let us know if you see anything wrong with this approach. 🍻

[strarsis]

Could this be helpful?: https://github.com/strarsis/sass-include-paths