Adding applications and features
Last Updated:
Almost everyone working on VA.gov at some point will need to build a new feature, something that doesn't fit into the existing applications or widgets we have currently. This article will help guide you to the right way to implement that new feature.
Types of features on VA.gov
Broadly, we have three kinds of features on VA.gov: static content pages, applications, and widgets.
Content pages
Static content pages are pages that are built through the Metalsmith build process and are static HTML stored in AWS. If you're reading this site, you're probably not the person who would be adding one of these pages. Typically these pages are added by content editors in the Drupal CMS which is the primary source of content. You may, however, be tasked with adding more complex behaviors to these pages, which is discussed later in the widgets section.
Note: In some rare cases, a site may use the Interim CMS instead of Drupal. See this repository for information about how to add pages and edit content in that system.
Widgets
On VA.gov, we use the term "widgets" to describe features that implement some kind of dynamic behavior in a contained place on a page. Examples of this include our saved application widgets, which display information about in progress applications a signed-in user may have, which is shown on various static content pages. Typically these widgets are written in React and are lazily loaded in separate bundles from the default static pages JS bundle.
Applications
The third type of feature are applications. These are Javascript applications, written with React/Redux, that control all of the UI for a page and may have multiple client-side pages. There is a static content page for each of these applications that contains only a header, footer, and div for the React application to mount to. These applications have their own JS bundle and the most flexibility for how to render content for a Veteran to interact with.
Examples of applications include our multi page forms, the claim status tracker app, etc.
Choosing the right type
Generally, you want to start with a simple content page, see if that will cover your needs, and if not, move up to an application widget. If that still isn't enough, then you can create an application. Full Javascript applications come at a cost for users, so we should make sure they're justified by the requirements of the feature you're building.
Content pages are the best choice if:
The content on the page or pages you need are completely static and don't change based on api or user data
Widgets are the best choice if:
You need to implement some kind of dynamic behavior based on user input or api data
The dynamic behavior you need is a small part of the overall page
You want content editors to have control over most of what is on the page or pages
You have multiple pages with the same dynamic behavior and want to share code between them
Applications are the best choice if:
Your feature has multiple pages that need to be dynamically created based on user input or api data
Your feature requires a lot of interaction and very little of the page you need is static
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.