Awesome

USWDS Compile

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

Requirements

• Node.js (v20 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.

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.

Additional settings

Functions

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

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.updateUswds = 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 updateUswds

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.
• Stay up-to-date with USWDS with updateUswds. When updating your project's version of USWDS, run the npx gulp updateUswds command to copy any updated USWDS assets into your project. Alternatively, you can run the copyAssets task. These tasks update USWDS static assets (like images, fonts, and compiled JavaScript) and will not override any of your project customizations. These actions might introduce breaking changes, so be sure to check out the related USWDS releases notes for any additional tasks that must be completed when updating to a new version of USWDS.
• 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

:rocket: