Download the PHP package va-gov/content-build without Composer

VA.gov Content Build

What is this?

This repository contains scripts and templates which generate static HTML pages for the VA.gov site.

There are several repositories that contain the code and content used to build VA.gov. If you're looking to get started running VA.gov locally, you should read the Setting up your local frontend environment documentation.

Common commands

Once you have the site set up locally, these are some common commands you might find useful:

Building static content

VA.gov contains many pages that include content generated from a Drupal-based content model. When testing changes to static pages, or to see what your application looks like on VA.gov, follow the sections below to build these static pages.

Note: Fetching content from Drupal requires SOCKS to be set up and running. Run vtk socks on in your terminal before attempting to pull any Drupal content for content-build.

Prepare Your Environment Settings

The Content-Build can pull fresh content directly from Drupal endpoints. To do this the request for content must be authenticated. If pulling fresh content you must ensure that these command line arguments or environment variables are set:

Authentication credentials are stored in a local .gitignore'd file .env. An example file is provided to get you started:

cp .env.example .env

File contents:

In most cases, these values will be all you need to run a content build with fresh CMS content. However, if you need to connect to a different CMS endpoint, you can either override the values in the .env file, or else override specific values at the command line. For example:

yarn build --pull-drupal --drupal-address=https://some-other-endpoint.cms.va.gov

If you do need to pull content from https://prod.cms.va.gov please contact #cms-support and request a user with permissions to read the Drupal Content API. You will need to use your assigned credentials to access Production.

Build static pages using the following commands:

yarn build (fetches the latest content cache from S3 by default when cache is empty)

Note: running yarn build on main can take upwards of 8 hours. There are many Drupal assets to fetch and many templates to build. See Optimizing Build Time below to cut down on this time dramatically and only build the templates/assets you need for your development work.

• use --pull-drupal to fetch fresh content from Drupal if needed (requires SOCKS proxy access). Add --use-cached-assets to skip asset download
• creates symlink to ../vets-website/build/localhost/generated by default, allowing access to app bundles (use --apps-directory-name to change the default apps directory name; e.g. --apps-directory-name application)
• run once to build the static HTML files
• need to run this again when adding new templates based on new Drupal entities

yarn serve

• starts a local server for the site using the latest build
• use --port to set the port for the server (3002 by default)
• use --buildtype to set the build type (localhost by default)

yarn watch

• watches for changes to liquid templates

yarn preview

• You can run this concurrently with yarn watch. It adds local routes needed to preview Drupal nodes (e.g. /preview?nodeId=XX).

If you do not have access to the SOCKS proxy, you can fetch the latest cached version of the content with the following:

Troubleshooting

The vagov-content repository sits adjacent to content-build in the same way that vets-website does. The markdown files in vagov-content are pulled in during the build process. If a markdown file is present in vagov-content, but the template was deleted in content-build, you'll see a build error that reads something like this:

If this happens to you, make sure you have the latest from the vagov-content on your local machine, and try building content-build again.

Optimizing Build Time

Another method to optimize your build / watch time for content-build is to ignore templates and assets that you do not need for local testing. For instance, if you are only working on Campaign Landing Pages, you can skip building a lot of the other content types (such as Resources & Support pages and Events). If you do not need to pull any Drupal assets (such as images), you can skip that step too. This will tremendously speed up your build time.

1. Open src/site/stages/build/drupal/individual-queries.js
2. Find the getNodeQueries function

3. Comment out any content types you will not need (leaving in basic page / landing page queries just in case). If you're working on Campaign Landing Pages, your function might look like this:

4. Open src/site/stages/build/index.js
5. Find this line: smith.use(downloadDrupalAssets(BUILD_OPTIONS), 'Download Drupal assets'); and comment it out
6. Delete your .cache/localhost/drupal/pages.json file
7. Make sure you are running SOCKS (vtk socks on)
8. Run yarn build --pull-drupal && yarn watch in your terminal to get the dev server running with your new template selections

Working in GitHub Codespaces

Read the Codespaces documentation for this repository.

Running tests

Unit tests

To run all unit tests, use:

If you want to run only one test file, you can provide the path to it:

To run all tests in a directory, you can use a glob pattern:

More commands

After a while, you may run into a less common task. We have a lot of commands for doing very specific things.

Supported Browsers

Not a member of the repository and want to be added?

• If you're on a VA.gov Platform team, contact your Program Manager.
• If you're on a VFS team, you must complete Platform Orientation to be added to this repository. This includes completing your Platform Orientation ticket(s) in GitHub.