Simple Gulp 4.0 functions for copying USWDS static assets and transforming USWDS Sass into browser-readable CSS.
Install @uswds/compile
in the project root:
npm install @uswds/compile --save-dev
gulpfile.js
file in the project root that includes the following:
@uswds/compile
packagenpx gulp [function]
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:
@uswds/compile
packageHere'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 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 . |
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 |
Setting | Default | Description |
---|---|---|
sprite.projectIconsOnly |
false |
Include only the icons in paths.src.projectIcons in the icon sprite. |
settings.compile.browserslist |
["> 2%", "last 2 versions", "IE 11", "not dead"] |
Define the browserslist query for CSS prefixes generated by autoprefixer. |
settings.compile.sassSourcemaps |
true |
Include sourcemap when compiling SASS to CSS. |
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 |
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:
npx gulp compile
or npx gulp
npx gulp watch
npx gulp init
npx gulp updateUswds
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.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.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
.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.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.
uswds-icons
or material-icons
) to this directory. These icons will be added to the default USWDS icons in the sprite.uswds.paths.src.projectIcons
to this new directory. For example
uswds.paths.src.projectIcons = "./assets/img/my-icons";
compile
or the compileIcons
function to compile a new sprite. This sprite includes the USWDS default icons and the new project icons.usa-icons
, uswds-icons
, or material-icons
) to this directory. These will be the only icons included in the sprite.uswds.paths.src.projectIcons
to this new directory. For example
uswds.paths.src.projectIcons = "./assets/img/my-icons";
uswds.sprite.projectIconsOnly
to true
. For example
uswds.sprite.projectIconsOnly = true;
compile
or the compileIcons
function to compile a new sprite. This sprite will include only the new project icons.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: