Developer docs
Developer docs
Breadcrumbs

Running VA.gov locally

Before you begin

Be sure you have set up your local environment.

What the watch task does 

yarn watch

  1. Build

    1. vets-website

      1. Webpack manages this build pipeline. At a high level, this process:

        1. Starts Webpack's development server which

          • Builds the JavaScript and CSS bundles

          • Serves the JavaScript and CSS bundles built by Webpack as well as any scaffolded application pages http://localhost:3001

    2. content-build

      1. Metalsmith manages this build pipeline. At a high level, this process:

        1. Retrieves and builds all of the static pages sourced from vagov-content or Drupal

        2. Serves the static content built by Metalsmith at http://localhost:3002

  2. Output

    1. Metalsmith in the content-build repository outputs static pages tobuild/localhost

    2. Webpack in the vets-website repository development server has no output. JavaScript and CSS are kept on disk.

  3. Watch and rebuild

    1. Metalsmith in the content-build repository will rebuild static pages when changes are saved to templates or content in vagov-content

    2. Webpack in the vets-website repository will rebuild when changes are saved to JavaScript or SCSS

    3. Both updates require a browser refresh to see changes.

    4. Changes to build process or configuration files are typically not picked up, and require a restart of the watch task to become active.

Running VA.gov locally for specific environments

Typically, the reason for building the site locally like this is to build it in production mode and check that it is behaving as you'd expect. Most of the time, it's better to use the watch task to build the site locally since it is the most developer-friendly experience.

Environment

Build Command

Output directory

Run Command

localhost

yarn build

build/localhost

npx http-server -p 3001 build/localhost

http://dev.va.gov

yarn build --buildtype=vagovdev

build/vagovdev

npx http-server -p 3001 build/vagovdev

http://staging.va.gov

NODE_ENV=production yarn build --buildtype=vagovstaging

build/vagovstaging

npx http-server -p 3001 build/vagovstaging

http://www.va.gov

NODE_ENV=production yarn build --buildtype=vagovprod

build/vagovprod

npx http-server -p 3001 build/vagovprod

What the build commands do

  • create the static pages from the markdown content in the vagov-content repository and data queried from the Drupal API into their output directory.

  • create the JavaScript and CSS files with Webpack into /generated folder in their output directory with Webpack.

What the run commands do

Notes

  • Production-like builds are required for staging and production environments. NODE_ENV=production environment variable is required to be set when running these build commands

  • Deep-linking to urls that are rendered by React apps on VA.gov will not work when you run the site this way, as that relies on some server-side routing that is handled in nginx (or the Webpack dev server when running the watch task)

Running VA.gov locally for specific applications

Use these commands if you are only working in one or more specific application(s) and want to speed up build and watch times. This is highly recommended if your application(s) is isolated.

Build one or more application(s) with the --entry option 

$ yarn build --entry=static-pages,auth

Start the local development server for one or more application(s) with the --entry option 

yarn watch --env entry=static-pages,auth

Help and feedback