Federalist template using Gatsby and USWDS 2.0
See It Live
Local development is no different than any other Gatsby application. Node v8.x or 10.x is recommended.
git clone firstname.lastname@example.org:18F/federalist-gatsby-uswds-template.git
npm run developand the site will be viewable at localhost:8000
npm run buildbuilds the static site and assets in the
npm run serveserves the built static files at
npm run cleanremoves the built static file directories
Federalist supports sites generated using
node but the documentation, examples, and experience of most users involve using Jekyll. Meanwhile, Gatsby is a great fit for many government static sites as it allows for disparate data sources and uses React while the USWDS provides a wonderful foundation for building beautiful, 508-compliant sites. Currently, using USWDS with React takes a little bit of effort, so using them together here them demonstrates the possibility of doing so while acting as a testbed for future changes in USWDS to make this pairing easier in the future.
Gatsby on Federalist
- Federalist expects the output to be in a folder named
_sitebut Gatsby's output is placed in
publicand probably won't ever be configurable (Gatsby Issue). We address this in this repo by creating a symlink named
_sitethat points to
- Federalist's preview builds and builds without a custom domain will be served at a nested path instead of at the root of a domain (ex.
/site/18f/<repo_name>), causing internal, relative links to be incorrect. Gatsby provides the
Linkcomponent to manage internal links but needs to know the actual root of the website to generate correct URLs. We address this by configuring the
prefixPathin Gatsby by adding
pathPrefix: process.env.BASEURL || '/'to gatsby-config.js file in the root of the project and running the build in Federalist with the
- Like any
nodeproject on Federalist, this project must have a
federalistkey in the 'scripts' section of
package.json, here we have
"federalist": "npm run build -- --prefix-paths".
Gatsby Features Utilized
Display content from different data sources:
- local yaml file index.yml
- local Gatsby configuration gatsby-config.js
- local markdown file
- remote api (USASpending.gov)
- Use Gatsby Image to display optimized images
USWDS and Gatsby/React
The USWDS is geared toward being used in a drop-in/copy-paste fashion and the CSS works just fine in any scenario, but the JS that handles user interaction is not meant to be used alongside a library like React or in non-browser environments (Gatsby is server rendered). In time, some of these issues may become more tractable or disappear completely, but for now, to use the USWDS as-is in this application we:
Import the USWDS CSS in our layout css
Only load the USWDS polyfills in the browser
Shim transient dependencies so they only load in the browser
Create some helpful aliases
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.