paths.src.projectSass not used during complile

[smustgrave]

When running compile noticed the files in paths.src.projectSass are not called.

Some more background. We are hoping to have init output all of the uswds files (img, fonts, scss, and js) files into an assets folder.

Then in our theme folder we can import the scss file at will without editing it. Which makes updating much easier later. But currently uswds.paths.dist.theme is basically serving 2 purposes and think should be broken up into

uswds.paths.dist.theme and new path uswds.paths.dist.sass

[smustgrave]

I would expect init to output the scss files into the assets folder. But to compileSass using that folder + additional folders outside the assets folder.

[mejiaj]

@smustgrave can you share your gulpfile?

Then in our theme folder we can import the scss file at will without editing it. Which makes updating much easier later. But currently uswds.paths.dist.theme is basically serving 2 purposes and think should be broken up into

If that setting isn't working on expected we can take a look. Splitting it might not be necessary if we can verify and fix the paths.src.projectSass issue.

[smustgrave]

/*
* * * * * ==============================
* * * * * ==============================
* * * * * ==============================
* * * * * ==============================
========================================
========================================
========================================
----------------------------------------
USWDS SASS GULPFILE
----------------------------------------
*/
const uswds = require("@uswds/compile");

// Custom variables
const pkg = require('./package.json');
const {series, watch} = require("gulp");
const gulp = require('gulp');
const sassLint = require('gulp-sass-lint');
const eslint = require('gulp-eslint');
const rename = require("gulp-rename");
const path = require("path");
let uglify = require('gulp-uglify-es').default;
const del = require("del");

/**
 * USWDS version
 */

uswds.settings.version = 2;

/**
 * Path settings
 * Set as many as you need
 */

// Where to output
uswds.paths.dist.css = './css';

// Custom scss files
uswds.paths.dist.custom = './components/**';

uswds.paths.dist.fonts = './assets/fonts';
uswds.paths.dist.img = './assets/img';
uswds.paths.dist.js = './assets/js';
uswds.paths.dist.scss = './assets/scss';

uswds.paths.src.projectSass = './components/**';

// Custom Functions

function cleanJs() {
  return del([pkg.paths.dist.js]);
}

function cleanCss() {
  return del([pkg.paths.dist.css]);
}

function scssLint() {
  return gulp.src(pkg.paths.scss)
      .pipe(sassLint())
      .pipe(sassLint.format())
}

// After we let uswds compile build the css files we need to minify them.
// todo should we cleanup css output folder structure?
function minifyCss() {
  return gulp.src(pkg.paths.css)
      // .pipe(rename(function (file) {
      //   // this removes the last parent directory of the relative file path
      //   let parts = file.dirname.split("/");
      //   parts = parts.slice(1);
      //   parts = parts.join("/");
      //   file.dirname = path.dirname(parts + "/" + file.basename);
      //   // console.log("file.dirname = " + file.dirname);
      // }))
      .pipe(rename({"suffix": '.min'}))
      .pipe(gulp.dest(pkg.paths.dist.css));
}

function buildJs() {
  return gulp.src(pkg.paths.js)
      .pipe(uglify())
      .pipe(rename(function (file) {
        // this removes the last parent directory of the relative file path
        let parts = file.dirname.split("/");
        parts = parts.slice(1);
        parts = parts.join("/");
        file.dirname = path.dirname(parts + "/" + file.basename);
        // console.log("file.dirname = " + file.dirname);
      }))
      .pipe(rename({"suffix": '.min'}))
      .pipe(gulp.dest(pkg.paths.dist.js));
}

function jsLint() {
  return gulp.src(pkg.paths.js)
      .pipe(eslint())
      .pipe(eslint.format())
      .pipe(eslint.failAfterError());
}

/**
 * Exports
 * Add as many as you need
 */

// copyAll + compile
exports.init = uswds.init;

exports.compileSass = series(cleanCss, scssLint, uswds.compileSass, minifyCss);
exports.compileJs = series(cleanJs, jsLint, buildJs);
exports.compileAll = series(this.compileSass, this.compileJs);

exports.lint = series(scssLint, jsLint);

exports.watch = series(this.compileAll, () => {
  watch(pkg.paths.scss, series([this.compileSass]));
  watch(pkg.paths.js, series([this.compileJs]));
});

exports.updateUswds = uswds.updateUswds;

exports.default = uswds.compileSass;

[smustgrave]

It's a WIP. But idea being we output all uswds assets to it's own folder. Then in our components folder is where we add our own custom, any uswds varaibles, etc.

Reason we don't edit the scss files is because if they change in order to update we would have to manually merge them with any custom work. This helps keep things separate.

[mejiaj]

Okay, we'll take a look.

Btw, I hope you don't mind I added some formatting to your code example. You can learn more about code blocks and syntax highlighting in github docs.

[mejiaj]

Adding a breakdown of the problem; what's happening vs what's expected.

Actual User has set paths.src.projectSass for additional SASS files to watch for changes, but the changes there get ignored.

Expected Directory specified in paths.src.projectSass should be watched for changes based on README.md

[smustgrave]

Just wanted to follow up on this. The PR can confirm works

[smustgrave]

The added benefit of the PR is users can do something like this

`// Where to output uswds.paths.dist.css = './css';

// Custom scss files uswds.paths.dist.custom = './components/**';

uswds.paths.dist.fonts = './assets/fonts'; uswds.paths.dist.img = './assets/img'; uswds.paths.dist.js = './assets/js'; uswds.paths.dist.scss = './assets/scss';

uswds.paths.src.projectSass = './components/**';`

here developers can output the full uswds assets into a separate folder without needing to make any changes.

Inside your custom folder you just need to copy assets/scss/_uswds-theme-custom-styles file. and use that.

This makes updating INCREDIBLY easy as there won't be any conflicts. Because things are separate. Feel the current implementation mixes the uswds and custom scss files which could be a pain to update later.

[smustgrave]

Wondering if this can be elevated? Currently without an additional variable I don't see how projects are suppose to be able to update after that first init. Most projects I've dealt with uswds we don't check in the library but build them through deploys. With the current setup the scss files will be overridden over and over ensuring no customization..

[thisisdano]

OK, here's what I think the quick answer is here:

• Use init only once, don't use it for updating. Instead, use the copyAssets task for updating (this updates the static assets only and you don't risk clobbering).
• Use paths.dist.theme as the spot where you're keeping your active Sass files. This can be your custom project directory.
• Use our styles.scss as the Sass entry point — or recreate its functionality in an existing Sass entry point (as it seems like you're doing)
• Compile only from a single Sass entry point, defined in paths.dist.theme

More detail: https://github.com/uswds/uswds-compile/pull/26#issuecomment-1130232770

[smustgrave]

Still not sure if that solves the problem. If we don't checkin the uswds assets and instead choose to build them during the deploy process. Without an additional variable this couldn't work it seems? Because after your copyAssets you'll need to change a variable in the gulpfile.js to compile and that's not part many deploy processes? Could be wrong though

[smustgrave]

Think this one can fall back to our process. But could it be documented somewhere that init can only be ran once. And a good way to do updates for the scss files without losing changes

[amyleadem]

Thank you for the explanation, @thisisdano. I will close my PR as looks like everything is working as expected code-wise.

As discussed yesterday, I am reassigning this issue to you with the goal of evaluating the documentation around uswds-compile to see if there are any places where we can provide clarity of intent/best practices for use. Your comments on this were very helpful and it would be great to integrate some of it into site.

Related, there is an open issue for updating the Getting Started for Devs guide that appears to have some overlap. Including it here in case there is a need to coordinate: https://github.com/uswds/uswds-site/issues/1615

[smustgrave]

@mejiaj @thisisdano thank you for all the help with this ticket!