next-build

Front-end templating, build, and deploy for VA.gov CMS content.

Local setup

Prerequisites

• a local VA CMS instance
• NVM for node version management
• Yarn for package management
• Docker for the redis container

You should set these up before attempting to install the repo.

Basic local installation

1. Clone the repo if you haven't. git clone git@github.com:department-of-veterans-affairs/next-build.git

2. In the next-build/ directory, nvm use

3. Run yarn install-safe.

4. Copy envs/.env.example to envs/.env.local. This is a reasonable set of environment defaults for local development.

5. Make sure you have a local VA CMS instance running. Follow the CMS repo setup instructions if needed.

6. Run yarn setup to download compiled JS/CSS bundles from the vets-website S3 bucket. Static assets (images and fonts) are already included in the repo.

7. Run yarn dev.

You will now have a Next.js development server running at http://localhost:3999, which will refresh with changes to your local environment. (Note: your local port may differ if you changed the value for PORT in .env.local).

Environment Flags

The APP_ENV flag can be used to designate which .env file you want to use. Ensure your env files are in ./envs, and then run your build or dev command with a leading APP_ENV=local.

ie APP_ENV=local yarn dev

Ensure the value passed into APP_ENV matches the file name of the .env file you wish to use.

If no value is passed .env.local will be used as the default

Additional flags

Additional env flags can be set by prepending them with "--". To pass arguments through to the underlying utility (e.g. jest) use "--" as a separator.

Examples:

yarn dev --NEXT_PUBLIC_DRUPAL_BASE_URL https://staging.cms.va.gov -- --port 3003

yarn test -- path/to/file

Available env variables and underlying utility help can be viewed by appending -h to the yarn script: Examples:

yarn test -h

yarn build -h

Local CMS endpoint

To use the local CMS as an endpoint, follow the install directions for the CMS repo here.

While installing those dependencies, you will run mkcert -install. This certificate is used by ddev, and also needs to be used by next-build to enable connections over https:// locally.

Steps to do so: mkcert -CAROOT to find where the rootCA.pem was installed cp the/above/directory/rootCA.pem path/to/next-build/certs/rootCA.pem

This certificate should be git ignored by default. In your .env.local file, update the endpoints to:

# This is the standard lower environment for Content API.
#NEXT_PUBLIC_DRUPAL_BASE_URL=https://mirror.cms.va.gov
#NEXT_IMAGE_DOMAIN=https://mirror.cms.va.gov

# If running va.gov-cms locally
NEXT_PUBLIC_DRUPAL_BASE_URL=https://va-gov-cms.ddev.site
NEXT_IMAGE_DOMAIN=https://va-gov-cms.ddev.site

Now you can run yarn dev and data will be coming from your local CMS environment instead.

Local CMS Preview

To test the preview API route locally, you will also need to add public and private OAuth keys to your local clone of the va.gov-cms root directory at public.key and private.key respectively. These files are gitignored in the va.gov-cms repo.

-----BEGIN PUBLIC KEY-----
Retrieve this value from AWS SSM @ /cms/staging/drupal_api_users/next_build_api/public.key
-----END PUBLIC KEY-----

-----BEGIN RSA PRIVATE KEY-----
Retrieve this value from AWS SSM @ /cms/staging/drupal_api_users/next_build_api/private.key
-----END RSA PRIVATE KEY-----

See the Preview README for more information.

Local vets-website assets

By default, the yarn setup command pulls compiled JS/CSS bundles from the prod S3 bucket. This can be changed based on the BUILD_TYPE env var.

If you are actively developing in vets-website and want to test local changes against next-build, first run a local build in that repo to compile your desired changes. Be sure to check your node versions when switching between these repos! vets-website uses node 22, next-build uses node 24. Using the wrong version when building will cause errors in both repos!

Then running BUILD_TYPE=localhost yarn setup will create a symlink to the local compiled output instead of downloading from S3.

See ./scripts/yarn/vets-website-assets.js for more information.

Generating the static site

To generate the static pages for https://va.gov, run yarn export. This command will generate static pages for all paths that next-build is aware of.

To use the redis cache during your static build, run yarn redis before running yarn export.

This will start redis in a docker container via

docker run --name next-redis -p 6379:6379 -d redis

This container can be reached from your localhost (e.g. redis://localhost:6379). You can interact directly with the redis container by running yarn redis:cli. For more on how this project uses redis, check the caching readme.

Documentation (WIP)

• Template Migration
• Code Guidelines
• Testing
• TypeScript
• Working with other repos

Broken link scanner (lychee wrapper)

We include a convenience script to run Lychee per-site-page and produce per-page JSON + a combined CSV/JSON report.

Location: scripts/lychee-per-page-scan-and-merge.js

Basic usage examples (run from the repo root):

• Scan the first 100 URLs from the default urls.txt:

node scripts/lychee-per-page-scan-and-merge.js --sample-size 100

• Scan a single page using a temporary URL list:

printf '%s\n' 'https://www.va.gov/corpus-christi-vet-center/' > tmp-urls.txt
node scripts/lychee-per-page-scan-and-merge.js --urls-file ./tmp-urls.txt --sample-size 1
rm tmp-urls.txt

• Pass extra Lychee args (for example to set a custom User-Agent or Accept header):

node scripts/lychee-per-page-scan-and-merge.js \
   --sample-size 1 \
   --extra-lychee-args --user-agent 'lychee-bot/1.0' --accept 'text/html'

Available flags (with env-var fallbacks):

• --sample-size / -n (env: SAMPLE_SIZE)
• --urls-file (env: URLS_FILE) — defaults to ./urls.txt
• --lychee-chunk-size (env: LYCHEE_CHUNK_SIZE)
• --batch-concurrency (env: BATCH_CONCURRENCY)
• --lychee-max-concurrency (env: LYCHEE_MAX_CONCURRENCY)
• --lychee-timeout (env: LYCHEE_TIMEOUT)
• --lychee-retries (env: LYCHEE_RETRIES)
• --exclude (env: LYCHEE_EXCLUDE) — comma-separated list
• --fail-on-lychee-error (env: FAIL_ON_LYCHEE_ERROR)
• --fail-on-missing-tools (env: FAIL_ON_MISSING_TOOLS) — also enabled automatically on CI
• --parent-fetch-retries (env: PARENT_FETCH_RETRIES)
• --parent-fetch-retry-delay-ms (env: PARENT_FETCH_RETRY_DELAY_MS)
• --extra-lychee-args (env: EXTRA_LYCHEE_ARGS) — pass any additional lychee CLI options (must appear last on the command line)

Outputs:

• Per-page JSON files: ./lychee-pages/lychee-<safe-url>.json
• Combined JSON: ./lychee-pages-combined.json
• Combined CSV: ./lychee-pages-combined.csv

Notes:

• Flags override env vars; env vars remain supported for CI convenience.
• The script will fail early in strict mode if Lychee or Cheerio are missing (--fail-on-missing-tools or CI).
• Use --extra-lychee-args to pass any valid Lychee option; the script adds -- so options are parsed by Lychee correctly.