USWDS Compile 1.2.0

What's new in USWDS Compile 1.2.0

Features

• Updated Gulp to version 5. This removes the dependency vulnerabilities related to Gulp 4. (#96)
• Added a setting to turn off Sass sourcemaps. Now, you can set the
  new settings.compile.sassSourcemaps to false in your gulpfile.js to prevent the system from generating CSS sourcemaps. Thanks @mdmower-csnw! (#103)

Dependencies and security

Dependency name	Previous version	New version
autoprefixer	10.4.16	10.4.20
gulp	4.0.2	5.0.0
gulp-sourcemaps	3.0.0	--
postcss	8.4.31	8.4.40
sass-embedded	1.69.5	1.77.8
@uswds/uswds	3.7.0	3.8.1

0 vulnerabilities using npm audit.

Release TGZ SHA-256 hash: 53995f42af77dcf5a7f66e5adebeebf2742a662d3cf7a12587b38b22422db122

USWDS Compile 1.1.0

What's new in USWDS Compile 1.1.0

Features

• PNPM Support. Compile script is now compatible with PNPM (without any additional configuration required). Thanks @danielnaab.
  • PR: #76.
• Use USWDS 3.7.0. The version of USWDS was updated to latest release.
• Support for Node LTS 20. We updated the supported node version to 20.9.0.
  • PR: #78.

Bug fixes

Fixed incorrect paths in sourcemaps. Found a workaround to incorrect sourcemap paths being set. PR: #79.

Dependencies and security

✦ = Via overrides

Dependency name	Previous version	New version
autoprefixer	10.4.13	10.4.16
del	6.0.0	6.1.1
gulp-replace	1.1.3	1.1.4
postcss	8.4.19	8.4.31
sass-embedded	1.56.1	1.69.5
@uswds/uswds	3.3.0	3.7.0
uswds	2.13.3	2.14.0
glob-parent ✦	-	6.0.2
unset-value ✦	-	2.0.1

3 moderate severity vulnerabilities using npm audit.

USWDS Compile 1.0.0

USWDS Compile 1.0.0

Simple Gulp 4.0 functions for copying USWDS static assets and transforming USWDS Sass into browser-readable CSS.

Requirements

• Node.js (v15 or higher)
• npm
• uswds

Installation

Install @uswds/compile in the project root:

npm install @uswds/compile --save-dev

Usage

Overview

1. Create a gulpfile.js file in the project root that includes the following:
   • Imported @uswds/compile package
   • Any project path settings you wish to modify (see Path settings, below)
   • Exports for the functions/tasks you need (see Functions, below)
2. In the terminal run npx gulp [function]

Gulpfile setup

Create a file called gulpfile.js at the root of your project (or use an existing Gulpfile if one already exists). It needs to do the following

• Import the @uswds/compile package
• Set any project settings
• Export the functions/tasks you need

Here's an example of how your gulpfile.js might look:

/* gulpfile.js */

const uswds = require("@uswds/compile");

/**
 * USWDS version
 */

uswds.settings.version = 3;

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

uswds.paths.dist.css = './assets/css';
uswds.paths.dist.theme = './sass';

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

exports.init = uswds.init;
exports.compile = uswds.compile;

USWDS version setting

USWDS is changing its file structure and package naming convention starting with USWDS 3.0. Use the USWDS version key to compile properly with the version of USWDS you're using.

When migrating from USWDS 2.x to USWDS 3.x, simply update the value of settings.version to 3 once you've installed @uswds/uswds with npm.

Setting	Default	Description
settings.version	2	The major version of the uswds package used in the project. USWDS 2.x projects should use 2 and USWDS 3.x+ projects should use 3.

Path settings

Use path settings to customize where USWDS Compile looks for USWDS source and outputs processed files. The value of the default may depend on the USWDS version you've defined in settings.version. When applicable, the relevant value of settings.version precedes the default.

Setting	Default	Description
paths.src.uswds	2: "./node_modules/uswds/dist" 3: "./node_modules/@uswds"	Source location of the uswds package
paths.src.sass	2: "./node_modules/uswds/dist/scss" 3: "./node_modules/@uswds/uswds/packages"	Source location of the USWDS Sass
paths.src.theme	2: "./node_modules/uswds/dist/scss/theme" 3: "./node_modules/@uswds/uswds/dist/theme"	Source location of the USWDS theme files (Sass entry point and starter settings files)
paths.src.fonts	2: "./node_modules/uswds/dist/fonts" 3: "./node_modules/@uswds/uswds/dist/fonts"	Source location of the USWDS fonts
paths.src.img	2: "./node_modules/uswds/dist/img" 3: "./node_modules/@uswds/uswds/dist/img"	Source location of the USWDS images
paths.src.js	2: "./node_modules/uswds/dist/js" 3: "./node_modules/@uswds/uswds/dist/js"	Source location of the USWDS compiled JavaScript files
paths.src.projectSass	"./sass"	Source location of any existing project Sass files outside of paths.dist.theme. The watch script will watch this directory for changes.
paths.src.projectIcons	""	Source location of any additional project icons to include in the icon sprite. (Use only these project icons in the sprite by setting sprite.projectIconsOnly to true.)
paths.dist.theme	"./sass"	Project destination for theme files (Sass entry point and settings)
paths.dist.img	"./assets/uswds/images"	Project destination for images
paths.dist.fonts	"./assets/uswds/fonts"	Project destination for fonts
paths.dist.js	"./assets/uswds/js"	Project destination for compiled JavaScript
paths.dist.css	"./assets/uswds/css"	Project destination for compiled CSS
sprite.projectIconsOnly	false	Include only the icons in paths.src.projectIcons in the icon sprite.

Functions

Export USWDS Compile functions in your project's gulpfile.js to use them in your project.

Function	Description
compile	compileSass + compileIcons
compileIcons	Build the USWDS icon sprite into paths.dist.img
compileSass	Compile Sass into paths.dist.css
default	watch
copyAll	copyTheme + copyAssets
copyAssets	Copies all static assets: copyFonts + copyImages + copyJS
copyFonts	Copy USWDS fonts to paths.dist.fonts
copyImages	Copy USWDS images to paths.dist.img
copyJS	Copy USWDS compiled JavaScript to paths.dist.js
copyTheme	Copy USWDS theme files (Sass entry point and settings files) from the uswds package to paths.dist.theme
init	copyAll + compile
updateUswds	copyAssets + compile
watch	Compiles, then recompiles when there are changes to Sass files in paths.dist.theme and paths.src.projectSass

Running the compile functions

For any function you defined as an export in your gulpfile.js you can run npx gulp [function]

For example, if you have the following gulpfile.js:

/* gulpfile,js */

...

exports.compile = uswds.compile;
exports.watch = uswds.watch;
exports.init = uswds.init;
exports.update = uswds.updateUswds;
exports.default = uswds.watch;

With that setup, you could do the following in the terminal:

• Compile Sass: npx gulp compile or npx gulp
• Watch for changes and recompile: npx gulp watch
• Initialize a new project: npx gulp init
• Update USWDS static assets and recompile: npx gulp update

Usage tips

• Use init only once. The init task is meant for initializing the design system on a project. Since it will overwrite project files (like settings files and the Sass entry point), use it sparingly and don't use it for updating the design system on a project, or at any point after you've customized your settings files.
• Update USWDS assets with copyAssets. Don't update assets with init, use the copyAssets task. This task updates static assets (like images, fonts, and compiled JavaScript) only and you don't risk clobbering your customizations.
• Compile only from a single Sass entry point. Define the location of this entry point with paths.dist.theme. If you have project Sass files outside the paths.dist.theme directory, load these files into your single entry point via @forward, @use, or @import. To include these project Sass files in your gulp watch task, set paths.src.projectSass to your project Sass directory. The Sass will still compile from the single entry point located in paths.dist.theme.
• Only check theme files and custom icons into version control. You should have a build process that copies static assets like images, fonts, and compiled JavaScript from the uswds package. This assures that these assets are up-to-date with whatever version of USWDS you're using. You only need to track your customizations (like settings, theme files, custom icons, and your gulpfile) in version control.

Updating the USWDS icon sprite

After running either init or copyAssets, you'll find USWDS images in the paths.dist.img directory. Any icon SVG file in usa-icons directory within the paths.dist.img directory will compile into the icon sprite when running the compileIcons function.

Add icons to the icon sprite

1. Create a directory for the new icons anywhere in your project
2. Add icons (typically from either uswds-icons or material-icons) to this directory. These icons will be added to the default USWDS icons in the sprite.
3. In your project Gulpfile, set uswds.paths.src.projectIcons to this new directory. For example

   uswds.paths.src.projectIcons = "./assets/img/my-icons";

4. Run either the compile or the compileIcons function to compile a new sprite. This sprite includes the USWDS default icons and the new project icons.

Use only project icons in the icon sprite

1. Create a directory for the new icons anywhere in your project
2. Add icons (typically from either usa-icons, uswds-icons, or material-icons) to this directory. These will be the only icons included in the sprite.
3. In your project Gulpfile, set uswds.paths.src.projectIcons to this new directory. For example

   uswds.paths.src.projectIcons = "./assets/img/my-icons";

4. In your project Gulpfile, set uswds.sprite.projectIconsOnly to true. For example

   uswds.sprite.projectIconsOnly = true;

5. Run either the compile or the compileIcons function to compile a new sprite. This sprite will include only the new project icons.

Autoprefixer

We use Autoprefixer for maximum browser compatibility. We target the the following browsers. When you compile with the USWDS compiler, we will apply Autoprefixer to all compiled code.

> 2%
last 2 versions
IE 11
not dead

Security

Package changes since Beta 3:

package	old	new
autoprefixer	10.4.7	10.4.13
postcss	8.4.8	8.4.19
postcss-csso	5.0.1	6.0.1
sass-embedded	1.50.1	1.56.1

Added uswds and @uswds/uswds to dev dependencies for testing.

6 high vulnerabilities using npm audit

USWDS Compile 1.0.0 Beta 3

What's new in USWDS Compile 1.0.0 Beta 3

Allow compiling on M1 Macs. Updates to a more modern SVG sprite compiler (gulp-svgstore) to resolve an incompatibility with M1 Macs and ARM-based chips.

Allow custom icons directory. You can now pass an optional directory (paths.src.projectIcons) whose contents will either add to (the default) or replace the contents of the icon sprite (with sprite.projectIconsOnly = true).

API updates

Setting	Default	Description
paths.src.projectIcons	""	Source location of any additional project icons to include in the icon sprite. (Use only these project icons in the sprite by setting sprite.projectIconsOnly to true.)
sprite.projectIconsOnly	false	Include only the icons in paths.src.projectIcons in the icon sprite.

Security

package	old	new
gulp-svg-sprite	1.3.7	REMOVED
gulp-svgstore	—	9.0.0

Added uswds and @uswds/uswds to dev dependencies for testing.

6 high vulnerabilities using npm audit

USWDS Compile 1.0.0 Beta 2

Improve compile speed. Replaces the sass package with the sass-embedded package to improve compile performance by about 40-50%.

Sass embedded:

This package is an alternative to the sass package. It supports the same JS API as sass and is maintained by the same team, but where the sass package is pure JavaScript, sass-embedded is instead a JavaScript wrapper around a native Dart executable. This means sass-embedded will generally be much faster especially for large Sass compilations, but it can only be installed on the platforms that Dart supports: Windows, Mac OS, and Linux.

Despite being different packages, both sass and sass-embedded are considered "Dart Sass" since they have the same underlying implementation. Since the first stable release of the sass-embedded package, both packages are released at the same time and share the same version number.

https://www.npmjs.com/package/sass-embedded
https://github.com/sass/embedded-host-node

Security

11 vulnerabilities (5 moderate, 6 high) using npm audit

USWDS Compile 1.0.0 Beta 1

What's new in USWDS Compile Beta 1

Allow for migrating to USWDS 3.0. Adds the settings.version key to set whether you're using USWDS v2 or USWDS v3 source path defaults. The default is 2. When you're ready to migrate to USWDS 3.0, install @uswds/uswds (the USWDS 3.0 package), then set settings.version = 3 in your gulpfile.js.

To compile using USWDS 2.0

Do nothing, settings.version = 2 is the default.

To compile using USWDS 3.0

/* gulpfile.js */

const uswds = require("@uswds/compile");

uswds.settings.version = 3; // compiles from @uswds/uswds 

...

Security

11 vulnerabilities (5 moderate, 6 high) with npm audit

USWDS Compile 1.0.0 Beta 0

No code changes from the last Alpha release.

USWDS Compile 1.0.0 Alpha 0

USWDS Compile

Simple Gulp 4.0 functions for copying USWDS static assets and transforming USWDS Sass into browser-readable CSS.

Requirements

• Node.js
• npm
• uswds

Installation

Install @uswds/compile in the project root:

npm install @uswds/compile --save-dev

Usage

Overview

1. Create a gulpfile.js file in the project root that includes the following:
   • Imported @uswds/compile package
   • Any project path settings you wish to modify (see Path settings, below)
   • Exports for the functions/tasks you need (see Functions, below)
2. In the terminal run npx gulp [function]

Gulpfile setup

Create a file called gulpfile.js at the root of your project (or use an existing Gulpfile if one already exists). It needs to do the following

• Import the @uswds/compile package
• Set any project settings
• Export the functions/tasks you need

Here's an example of how your gulpfile.js might look:

/* gulpfile.js */

const uswds = require("@uswds/compile");

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

uswds.paths.dist.css = './assets/css';
uswds.paths.dist.sass = './sass';

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

exports.init = uswds.init;
exports.compile = uswds.compile;

Path settings

Use path settings to customize where USWDS Compile looks for USWDS source and outputs processed files.

Setting	Default	Description
paths.src.uswds	"./node_modules/uswds/dist"	Source location of the uswds package
paths.src.sass	"./node_modules/uswds/dist/scss"	Source location of the USWDS Sass
paths.src.theme	"./node_modules/uswds/dist/scss/theme"	Source location of the USWDS theme files (Sass entry point and starter settings files)
paths.src.fonts	"./node_modules/uswds/dist/fonts"	Source location of the USWDS fonts
paths.src.img	"./node_modules/uswds/dist/img"	Source location of the USWDS images
paths.src.js	"./node_modules/uswds/dist/js"	Source location of the USWDS compiled JavaScript files
paths.src.projectSass	"./sass"	Source location of any exisiting project Sass files outside of paths.dist.sass. The watch script will watch this directory for changes.
paths.dist.sass	"./sass"	Project destination for theme files (Sass entry point and settings)
paths.dist.img	"./assets/uswds/images"	Project destination for images
paths.dist.fonts	"./assets/uswds/fonts"	Project destination for fonts
paths.dist.js	"./assets/uswds/js"	Project destination for compiled JavaScript
paths.dist.css	"./assets/uswds/css"	Project destination for compiled CSS

Functions

Export USWDS Compile functions in your project's gulpfile.js to use them in your project.

Function	Description
compile	compileSass + compileIcons
compileIcons	Build the USWDS icon sprite into paths.dist.img
compileSass	Compile Sass into paths.dist.css
default	watch
copyAll	copySetup + copyAssets
copyAssets	Copies all static assets: copyFonts + copyImages + copyJS
copyFonts	Copy USWDS fonts to paths.dist.fonts
copyImages	Copy USWDS images to paths.dist.img
copyJS	Copy USWDS compiled JavaScript to paths.dist.js
copySetup	Copy USWDS theme files (Sass entry point and settings files) from the uswds package to paths.dist.sass
init	copyAll + compile
updateUswds	copyAssets + compile
watch	Compiles, then recompiles when there are changes to Sass files in paths.dist.sass and paths.src.projectSass

Running the compile functions

For any function you defined as an export in your gulpfile.js you can run npx gulp [function]

For example, if you have the following gulpfile.js:

/* gulpfile,js */

...

exports.compile = uswds.compile;
exports.watch = uswds.watch;
exports.init = uswds.init;
exports.update = uswds.updateUswds;
exports.default = uswds.watch;

With that setup, you could do the following in the terminal:

• Compile Sass: npx gulp compile or npx gulp
• Watch for changes and recompile: npx gulp watch
• Initialize a new project: npx gulp init
• Update USWDS statci assets and recompile: npx gulp update

---

Autoprefixer

We use Autoprefixer for maximum browser compatibility. We target the the following browsers. When you compile with the USWDS compiler, we will apply Autoprefixer to all compiled code.

> 2%
last 2 versions
IE 11
not dead

---

Updating the USWDS icon sprite

After running either init or copyAssets, you'll find USWDS images in the paths.dist.img directory. Any icon SVG file in usa-icons diretory within the paths.dist.img directory will compile into the icon sprite when running the compileIcons function.

We'll be updating and improving the icon workflow in subsequent releases.

🚀