Add a new application or feature to VA.gov

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 addding one of these pages. Typically these pages are added by content editors in the vagov-content repo or in the Drupal CMS. You may, however, be tasked with adding more complex behaviors to these pages, which is discussed later in the widgets section.

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 dyanmically 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