Set up your local build environment | New Relic Documentation

Running the site locally makes testing and previewing large changes much easier. There are several things you need to do get this working. Fortunately, you only need to do this once.

Using the terminal and command line

On macOS, you can use the Terminal app to access your system's command line. (You can also access the terminal via VS Code.) The command line is an alternative to the graphical user interface.

Here are some basic terminal commands that might be useful:

pwd (print working directory): Use this to see your directory path.
ls (list): Shows the files in your current directory.
cd YOUR_DIRECTORY_PATH (change directory): Moves to another directory.
cd ..: Move one directory up in your path.

0. Enable VS Code in your terminal

It's handy to be able to open files from your terminal directly in VS Code. You may only use this a couple of times, but it's much nicer than trying to edit files in the terminal itself.

Open Visual Studio Code.
Press command + shift + p to open the command palette, then type "install code", and then click Shell command: Install 'code' command in PATH.
In your terminal, type code YOUR_FILENAME` to open that file in VS Code.

1. Use GitHub Desktop to set up your local repository

GitHub Desktop is a graphical tool for managing your branches, commits, and PRs. It's probably the most straightforward way to work with Git and GitHub.

Install GitHub Desktop.
Sign in to GitHub Desktop via your GitHub account.
- On Macs, click on GitHub Desktop in the top left corner of your screen and select Preferences. Select the blue Sign In button and follow the prompts in the browser window.
Navigate to the Docs Site repository.
Click the green Code button and select Open with GitHub Desktop.
Choose the location where you want the repo. The default location for this folder is ~/Documents/github.
Clone the entire repository to your local machine.

2. Enable Full Disk Access

By default, it seems that macOS prevents the terminal from access to certain system folders, like Documents. Change this setting to make it easier to navigate in your file system via the terminal.

Open System Preferences.
Click Security & Privacy.
In the left pane scroll down until you find Full Disk Access and then select it.
Click the lock in the bottom left corner and then enter the password you use to log in to your computer.
In the list of apps, check the box next to Terminal (or whatever your default terminal application is).
Click the lock to lock it.

3. Install Homebrew

Homebrew is command line tool for installing other applications. It's also an easy way to keep command line software updated.

Open your terminal.
Copy and paste this command to your terminal:

bash

$/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

4. Install npm

npm stands for Node package manager. You use this to install nvm, which stands for Node version manager.

In your terminal, type brew install npm.

5. Install nvm

Node version manager, or nvm, is what you use to manage the version of Node installed on your computer.

In your terminal, type npm i -g nvm.

6. Add nvm to your shell profile

In order to run the commands you need for your local build, you need to add the path to nvm to your shell profile.

On macOS, your shell is what interprets what you enter on the command line. The default macOS shell is Zsh. You need to tell your shell the directory where nvm is on your machine, so you can run these commands from anywhere.

You do this by adding some text to your .zshrc file, which is a config file for your shell.

In your terminal, type code ~/.zshrc to open this file in VS Code.
In the .zshrc file, copy and paste this text:

bash

$export NVM_DIR="$HOME/.nvm"
$[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
$[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Save the file.

7. Install Node

Once you've installed nvm, you can install the correct version of Node. Node, or Node.js, is the JavaScript engine that powers our Gatsby site and its dependencies.

Type nvm use 16 to install Node version 16.

8. Install Yarn

Yarn is another package manager used to compile all of the files in the docs-website repo to build the site locally. You use npm to install Yarn.

In your terminal, type npm i -g yarn.

Build the local site

Once you've installed all of these things in your terminal, you can run the site locally on your machine.

In your terminal, type pwd to make sure you're in the docs-website repository directory.
Type yarn to make sure all your Gatsby dependencies are up to date.
Type yarn start to build the site locally.
When the process finishes, in your web browser, go to http://localhost:8000.

When you run yarn start, your terminal outputs many lines of text. If your local build fails, the terminal output often provides a clue to what's gone wrong.