In general, front end code is in the frontend directory.
This guide is about the nuts-and-bolts of developing front end code; for details on how to use or style individual components, see the style guide.
The static asset generator¶
If you haven’t already, make sure you’ve followed the
setup guide; it explains how to run
which (among other things) will watch for changes to front end
code and re-build bundles as needed.
located in the frontend/source/ directory. Outputs
from the static asset generator are placed in
Examine gulpfile.js for details about the generator’s pipeline.
If you just want to build the assets once without watching for changes, run:
docker-compose run app yarn gulp build
Developing the front end¶
Globally, we use yarn to manage our node dependencies and run node tasks.
yarn, in addition to being faster than using
npm install, has the
benefit of locking dependency versions via a
Read the yarn workflow docs if you are not familiar with how to use it.
Parts of the site use React and Redux. More information available below.
We use Sass for our stylesheets. Their basics guide is a good place to start if you’ve not used it before. Sass allows us to abstract frequently used parts of the CSS into reusable components like variables and mixins. Some variables come directly from the U.S. Web Design System and we define new values for them in frontend/source/sass/base/_uswds_variables.scss. Other variables are specific to CALC, and those are defined in frontend/source/sass/base/_variables.scss.
This project generally follows a modified BEM (Block, Element, Modifier) naming scheme. This prevents namespace collisions and alleviates the need for too much nested Sass.
The Sass files follow a few conventions:
- Core styles are divided into four categories: admin (controls styling for the Django site admin), base (styles like resets, grid, and variables), components (individual site components like the header and footer), and libs (vendored CSS).
- All of the site’s core styles are imported in frontend/source/sass/main.scss.
- Partials (also called includes or imports) are files that will get compiled into the main CSS file. These are prefixed
with an underscore (such as
A more detailed explanation of how to use specific components can be found in the CALC style guide.
Site section-specific implementation details¶
Different parts of CALC are constructed in different ways, so developing the front end depends on which part you want to change.
There are three distinct sections of the site that rely on different technologies:
The data explorer (the publicly available tool that lives at
the data capture tool (which encapsulates both the workflow that starts at
calc.gsa.gov/data-capture/step/1 and the bulk upload available to site admins
calc.gsa.gov/data-capture/bulk/region-10/step/1), and the site admin
(the place site admins can approve submitted price lists, manage users, and more,
To run all the tests, run:
docker-compose run app yarn test
You can also run the tests in a continuous “watch” mode, which re-runs tests as you change your code:
docker-compose run app yarn test:watch
You can run
jest directly, too:
docker-compose run app jest, followed by any Jest CLI options.
To see a visual representation of the bundles generated by Webpack, you can use
docker-compose run app yarn gulp build docker-compose run -p 8888:8888 app yarn analyze-webpack
Then visit http://localhost:8888 to explore the modules that comprise each bundle.
Data capture largely consists of Django templates combined with HTML5 Custom Elements to provide a progressively-enhanced experience.
The source code is located in frontend/source/js/data-capture.
We skin the Django administrative UI to look like part of the CALC site; its templates are located in calc/templates/admin.