USWDS-Compile - Feature: Ability to specify external packages

[jcandan]

Is your feature request related to a problem? Please describe.

I have built the beginnings of a USWDS 3 custom design system package. Instead of using USWDS on a single project, and customizing it each time we use it in a new project, this will lay the foundation for us to have consistency across organization projects.

Describe the solution you'd like

To accomplish this, it was necessary to override the buildSass function.

-  return src([`${paths.dist.theme}/*.scss`.replaceAll("//", "/")])
+  return src("src/stylesheets/mywds.scss")
...
-      sass({ includePaths: buildSettings.includes }).on("error", handleError)
+      sass({
+        includePaths: [
+          "./packages",
+          "./node_modules/@uswds/uswds/packages"
+        ],
+        outputStyle: "expanded",
+      }).on("error", handleError)
...
-    .pipe(sourcemaps.write("."))
-    .pipe(dest(paths.dist.css));
+    .pipe(dest("dist/css"))
+    .pipe(postcss(pluginsMinify))
+    .pipe(rename({
+      suffix: ".min",
+    })
+    )
+    .pipe(sourcemaps.write("."))
+    .pipe(dest("dist/css"));

Note:

For my design system package to be able to supply its own theme/ starter files to projects that require it, I had to specify a different source than what is copied from uswds.paths.dist.theme:

So, it seems then that we need:

1. The ability to optionally specify a compile source that is different from the theme source.
2. The ability to override the includePaths key of the buildSettings object, and set outputStyle: "expanded".
3. The ability to optionally specify a different destination than uswds.paths.dist.css.
4. The un-minified and minified output.

Describe alternatives you've considered

No response

Additional context

With this change, we could document how an organization can build their own USWDS packages to support their entire organization. This also opens up the possibility for community driven packages.

Code of Conduct

• [X] I agree to follow this project's Code of Conduct.
• [X] I checked the current issues for duplicate feature requests.

[ekubovsky]

Facing the same issue - buildSass() has some hard-coded configs that we wish were available to override. I am going to look into a way to patch the original file to make that possible.

[jcandan]

CC @mejiaj @mahoneycm

[mejiaj]

@jcandan thanks for submitting this issue!

A few questions to clarify the request…

1. Compile source different than theme source

Can't you set this currently via uswds.paths.dist.theme or paths.src.projectSass?

// your-gulpfile.js

uswds.paths.dist.theme = "src/stylesheets/mywds.scss"

// Alternatively, other project SASS files.
uswds.paths.src.projectSass = "src/stylesheets/mywds.scss"

2. Override includePaths and outputStyle

This is a good idea and we should include. Captured in #80 and #113.

3. Optionally specify uswds.paths.dist.css

You should be able to do this via the setting.

// your-gulpfile.js
uswds.paths.dist.css = "./another/folder/to/save/"

4. Minified vs unminified output

Captured in #80.