Development tips

EditorConfig

We support EditorConfig. EditorConfig is a plugin for editors that allows for easy and quick configuration of editors for multiple properties. Feel free to install a plugin for your editor.

Main front-end template/asset locations

Templates that are served by the Django server: cfgov/jinja2/v1

Static assets prior to processing (compilation, minification, etc.): cfgov/unprocessed.

Note

After running yarn build (or ./setup.sh) the site's assets are copied over to cfgov/static_built, ready to be served by Django.

Serving a local frontend build in Docker

Our Docker image builds the frontend when the image is built, and stores the result in /srv/cfgov-static-built inside the container. Django serves assets from there, so a plain docker compose up works without requiring a local frontend build.

That location lives outside of the container's /src/consumerfinance.gov working directory, which docker-compose.override.yml replaces with a mount of your local repository. This means that the assets built into the image aren't hidden by, and don't get confused with, anything in your local cfgov/static_built.

If you're working on the frontend, you'll instead want Django to ignore that build and serve the assets that you build yourself. Uncomment this line in your .env file to clear the path to the prebuilt assets:

export PREBUILT_STATIC_PATH=

and restart the container. With this variable unset, Django will read assets from the cfgov/static_built directory in your mounted repository. yarn build and yarn watch will then reflect changes on your local machine.

Note

Only our Docker image ships prebuilt assets via the PREBUILT_STATIC_PATH variable. If you run the site outside of Docker, in a virtualenv, nothing should set that variable. Django will read from cfgov/static_built in that case as well.

Adding new Javascript entrypoints

  • In order to build standalone javascript files that are to be included in a template, they need to be included in the jsPaths variable in esbuild/scripts.

Installing new front-end dependencies

  • Use yarn add new_dep@se.m.ver to install new dependencies or update existing dependencies.
  • In the rare but observed case that yarn add new_dep@se.m.ver doesn't add every needed package to the offline cache, you likely need to first run yarn cache clean.

Watching files for changes

Any JavaScript or SASS file that is included as an entrypoint in esbuild can automatically trigger rebuilds with yarn watch.

Developing on nested satellite apps

Some projects can sit inside consumerfinance.gov, but manage their own asset dependencies. These projects have their own package.json and base templates.

The structure looks like this:

npm modules

  • List an app's own dependencies in cfgov/unprocessed/apps/[project namespace]/package.json.

App build scripts

  • Apps may include their own scripts to run during the build process These must be required from esbuild/build.js

Adding Images

  • Images should be compressed and optimized before being committed to the repo
  • In order to keep builds fast and reduce dependencies, the front-end build does not contain an image optimization step
  • A suggested workflow for those with Adobe Creative Suite is as follows:
  • Export a full-quality PNG from Adobe Illustrator
  • Reexport that PNG from Adobe Fireworks as an 8-bit PNG
  • Run the 8-bit PNG through ImageOptim

Templates

  • Apps use a Jinja template that extends the base.html template used by the rest of the site. This template would reside in cfgov/jinja2/[project namespace]/index.html or similar (for example, know before you owe).

Note

A template may support a non-standard browser, like an older IE version, by including the required dependencies, polyfills, etc. in its template's {% block css %} or {% block javascript scoped %} blocks.