Setting up your local frontend environment

A step-by-step guide to setting up the VA.gov frontend environment locally.

Step 1: Set up Node

Install nvm:
Please follow instructions in the nvm documentation for installing this dependency.
Install node 14.15.0 (this also installs npm):
BASH
```
nvm install 14.15.0
```
Configure nvm to use node 14.15.0 by default:
BASH
```
nvm alias default 14.15.0
```
Install yarn 1.19.1 globally:
BASH
```
npm i -g yarn@1.19.1
```
Verify correct versions of node and yarn are installed:
BASH
```
node --version # 14.15.0
yarn --version # 1.19.1
```

Step 2: Get the source code

Clone VA.gov git repos as sibling directories:

BASH

git clone git@github.com:department-of-veterans-affairs/vets-website.git
git clone git@github.com:department-of-veterans-affairs/vagov-content.git
git clone git@github.com:department-of-veterans-affairs/content-build.git
git clone git@github.com:department-of-veterans-affairs/vets-json-schema.git
git clone git@github.com:department-of-veterans-affairs/veteran-facing-services-tools.git
git clone git@github.com:department-of-veterans-affairs/vets-api.git
git clone git@github.com:department-of-veterans-affairs/vets-api-mockdata.git

Front end repos

vets-website: Core front end platform and application code
- vagov-content: Markdown content used to generate static pages
- content-build: Liquid templates and content build for static pages
- veteran-facing-services-tools: Shared front end components (including non VA.gov users) and front end documentation site

Back end repos

vets-api: Core Rails API server application code
- vets-api-mockdata: Mock data used when running locally and on dev for the backend

Shared repos

vets-json-schema: Shared JSON Schema definitions used by form applications and the APIs that they consume

Step 3: Start up the front end

vets-website

Navigate to the vets-website repository, then install vets-website dependencies. See these common commands for more information.
BASH
```
cd vets-website
yarn install
```
Build all applications for vets-website. Run this standard build script if you need all the CSS and JS generated for work in content-build.
BASH
```
yarn build
```
If you are only working in an Isolated application(s) (or do not need to build all applications), you can build one or more application(s) with the --entry option.
BASH
```
yarn build --entry=static-pages,auth
```
To get Intellisense in your IDE (autocomplete + cmd/ctrl-clicking on files) to work reliably, copy jsconfig-example.json to jsconfig.json and make adjustments in that file according to your project.
Start the local development server for all applications. If you are applying CSS and/or JS changes to a static page/template that renders in content-build, we recommend leaving this command running so you will be able to see the changes in content-build.
BASH
```
yarn watch
```
Again, you can limit the watch to one or more application(s) with the --entry option.
BASH
```
yarn watch --env entry=static-pages,auth
```
The watch is complete when the CLI says Compiled successfully.

If you would like webpack to open a browser window for you, please run yarn watch --open. We use Webpack DevServer to watch and serve the files locally; all the same options and documentation should apply.
Open http://localhost:3001 in a browser if you are working on an app; otherwise, continue on to the content-build section for viewing changes in the browser.

You can learn more about building applications in the vets-website GitHub readme.

content-build

In order to run content-build, you must first generate the CSS and JS files within vets-website (follow steps above). If you don't, you will see a build error in the console instructing you to first generate files in vets-website. If you are applying CSS and/or JS changes to a static page/template that renders in content-build (like the homepage) you will need to run a watch in vet-website to view the updates. The CSS and JS files within vets-website are locally connected through a symlink in the build process.

If you don't need to locally view static pages and are just working on applications, you don't need to set this part up.

Navigate to the content-build repository, then install dependencies via yarn.
BASH
```
cd content-build
yarn install
```
Content-build steps requires an additional set up step due to code changes in the app. If building content from Drupal, it requires a one-time setup of a .env file to supply connection information.
BASH
```
cp .env.example .env
```
Build content-build. Make sure you configured the SOCKS proxy to fetch content from Drupal. For a faster installation, use step 4 first.
BASH
```
yarn build
```
If you do not have access to the SOCKS proxy, you can alternately fetch the latest cached version of the content.
BASH
```
yarn fetch-drupal-cache
```
Start the local development server.
BASH
```
yarn watch
```
The watch is complete when the CLI says Compiled successfully. If you just need a server running without watching the metalsmith files you can run npx http-server . -p 3002 inside /build/localhost to save some CPU.
Open http://localhost:3002 in a browser.

Step 4: Backend and internal tools set up

Full backend support

Setting up the backend and internal tools allows local test account login and static content rendering.

Backend (vets-api) set up instructions.
The local vets-website is configured to point to the vets-api backend at http://localhost:3000. Any website functionality that depends on the backend (i.e. login, save-in-progress, form submission, feature toggles) will require a locally running instance of vets-api.
To log in with a test account locally, see instructions for how to access VA.gov in Staging
Internal tools setup instructions
This proxy setup is required to access static content locally and to access to our reporting and monitoring tools. Running the yarn watch task with the SOCKS proxy active will automatically pull and cache the static content for vets-website.

Mock API setup

Running a mock API for local development: This option will mock specific backend endpoints, but it is not comprehensive. You can modify the file to mock specific endpoints and supply the data that you need to test locally.

Troubleshooting

content-build

[Error: ENOENT: no such file or directory, open '{file path on your local machine}']

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.
Steps to Resolve.
- 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.

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.