Setup a Local Dev Environment

Back to: Create a Static Student Website

Establishing a workflow that embraces best practices

Web designers and developers typically work locally, on their personal computers, then upload their files to cloud-based, shared directories (e.g. Google Drive, DropBox, etc.), especially when working with teams on group projects. This daily workflow/process has become a standard best practice, especially for web developers. Coding technologies, tools, apps, and services like Github and VS Code (Visual Studio Code) make this practice easier, but it’s still hard for beginners. In this lesson and hands-on activity, we are going to walk through the process of setting up a local web development environment and establishing a daily workflow/routine to follow that embraces good web development principles and best practices.

Pre-requisites

This exercise assumes the following:

1. You should already have a Github pages repo setup (e.g. https://github.com/yourusername/yourusername.github.io). If not, please refer to the previous lesson.
2. You already have VS Code installed.
3. You already have git installed locally
   Not sure if you have git? Type this into your command line application (e.g. Terminal on a Mac, Command Prompt on a PC) to find out:

git --version

If the above command returns a successful git version number, like “git version 2.19.0” then you are all set. If not, you will need to install git.

TIPS FOR INSTALLING GIT AND SETTING UP YOUR HOME/PERSONAL COMPUTERS:

If you are using your personal computer (not a shared computer in a classroom), I suggest installing the following software before moving on to Step #1 below:

1. Download and Install Github Desktop. After you’ve installed it, launch it and login using your github credentials. Once successfully logged in, you can then quit out of GitHub Desktop. We are not going to use it. But… by installing it and opening it (even just once) it will help to do two things: 1) install git on your computer and 2) configure your git username and email address. Installing and configuring git manually can be done, but most students find it easier via the Github Desktop app. For more details on git and Github, see this Intro to Git Using GitHub lesson for more details.
2. MAC users: download and install X-Code from the Mac Store. Similar to GitHub Desktop, this software application will not be used in the following lessons, but some past students came across errors that required X-Code to be installed in order to resolve an error that you might run in to. It is also a helpful tool that you might use in the future to test your websites, so I recommend installing it anyway.

Ready? Created your GitHub Account? Able to get Git successfully installed OK? Nice Work!

Let’s start coding! Don’t be scared, just follow the steps below. Let’s do this!

Login to GitHub.com in your browser and create a new repo for your website..

For the students creating a student website, I suggest creating a repo named “studentsite.”

• Login to GitHub
  • Navigate to your Repositories page/tab
  • Create a new repo by clicking on the green “new” button in the upper right corner

• Be sure to name your new repo “studentsite” (all lowercase, no spaces)
• Be sure to check the box to initialize a README.md file
• Be sure to include a .gitignore (choose “Node” for now, we will modify later)

---

Launch Terminal app on your Mac (or Command Prompt on your PC) and navigate to the Desktop (or target parent directory) via the command line.

NOTE: the following instructions were written for students working on a school computer in a computer lab on campus. At the time this lesson was initially published, all students were on Mac computers. If you are following this on a PC, please do your best to try to mimic the steps accordingly.

• On your Mac, go to Applications > Utilities > Terminal:

• Once Terminal app is open, note the location, or directory that you are inside of by typing the following:
  • pwd
    • This command will display the path of the current directory (e.g. /Users/username). This should work for PC users, but if not, try typing in “cd” with nothing after it.
  • ls // for MAC users
    … or ..
    dir // for PC users
    • This command will list all of the contents inside of the current directory (e.g. files and folders)

• Typically, by default Terminal app will open up to the current user’s root directory (e.g. Users/username), which is one level up from the Desktop, so once you confirm that you are inside your user directory and need to go one level down to get to your Desktop, you can then change the current directory to the desktop via the following:
  • cd Desktop
    • This command (cd DirectoryName) will change the current directory to a target child directory, in this case Desktop

Other helpful Command line commands:

• cd ..
  • This will change the directory to one level up (go up one level to the parent folder)

If you will be working in a sub-folder, such as “SAVE FOLDER” > JohnDoe, then please navigate to the parent directory, which in this case would be johndoe (note that you should get in the habit of saving folders/directories with no spaces). If you need to cd into a folder with a space in the title, use quotes to do so, like this:

cd "Save Folder"
cd johndoe
pwd
/Users/student/Dekstop/Save Folder/johndoe

Use the pwd command to confirm that you are in the correct parent directory where you will be cloning (copying) your studentsite to work on it locally.

Git Clone (make a copy of) your Github “studentsite” repo locally

The next step is to clone (make a copy) your GitHub studentsite repo from the server (Github) and place it on the Desktop of your computer (or in your target sub-directory). Once you know that you are inside of your Desktop directory (or target parent folder) in Terminal app (use cd to change directories and pwd to confirm), then type git clone then a space then type the path to your repo from github with the following command:

• git clone https://github.com/username/studentsite
  • This command will copy the repo from github and place it on your local computer as a folder.
  • You can either type the url path manually or copy-paste the url from your browser
  • Be sure to change the path to match your github username and repo name

git clone https://github.com/username/studentsite

Errors?

If you receive any errors, it’s possible that git is not installed on the computer that you are working on, or you might be experiencing a similar/related technical problem. If this happens, try using Github Desktop to commit and push your changes. Be sure to log in first and double-check to ensure that your username and email addresses are entered correctly.

You will know that you are done with this step when you see the folder on your Desktop (or in your target folder via Finder. If for any reason you accidentally cloned it to the wrong folder, no worries: simply move it wherever you want.

Open up your repo in VS Code and update your README.md file with a link to your live GitHub pages site.

At this point, you are done with the command line (Terminal app or Command Prompt for PC users), so you can go ahead and close it. Next, we’re going to edit the site, starting with the README.md file. Launch your text editor (VS Code), and open your project folder. There are multiple ways to launch VS Code:

• You can go to Applications > VS Code, click on the icon in the Dock, or drag your folder directly onto the icon in the dock (recommended).

If you open VS Code manually by launching the application and not via dragging a folder, be careful not to edit the wrong project files. Whenever you launch VS Code, you always want to open a folder and double-check that you are in the correct folder before you start editing. On some computers, VS Code might automatically open the last project (folder) and files. If you are on a shared computer (e.g. a school computer lab), then you should get in the habit of double-checking the project/folder every time you launch VS Code. One way around this to drag your folder into VS Code via the dock.

TIP: To ensure that you open up your target project folder, try dragging and dropping your folder directly onto the VS Code Icon in the Dock (Mac users).

Once you are in VS Code, you can also open folders via the File menu:

1. Go to File > Open and browse to your project folder.
2. Go ahead and close the “Welcome” screen/tab (if it appears by default).

Next, open the README.md file and add the following link via markdown:

[View my site](https://username.github.io/studentsite)

When you are done editing the README.md file, hit save and you will notice a small blue circle with the number “1” in it. This is VS Code letting you know that a file was changed locally that is different than the master repo on github.com. This is a good warning notification (thank you VS Code).

Save (commit) your local changes to the server (Github) via VS Code’s built-in Git tab.

In VS Code, navigate to the “Source Control” (a.k.a. “Git”) tab on the left, then do the following:

1. Add a descriptive comment then hit the checkmark icon (the checkmark will save the changes via a git “commit”)
   • TIP: if you get a pop-up screen that asks if you would like to “stage” (add) your commit first, be sure to choose the “Stage Always” or “Yes, Do This Every Time” option (this will combine two commands into one—the “add” + “commit”—and will save you time and headaches in the future).
2. At the bottom of the interface, hit the sync icon (this sync icon will upload the changes via a git “push”)
   • WARNING: this icon may be different depending upon your setup, platform, version of VS Code, etc. For example, you might see a cloud icon with an arrow pointing upwards.
3. If prompted, enter your GitHub username and password at the top of the interface.
   • WARNING: If you are using a shared computer, you should be prompted for your github credentials. If you receive a permission error, you might need to clear the computer’s saved passwords (e.g. via Keychain access on a Mac). If you are using your personal computer, you should have no problems and only be prompted once (the first time).

Once you have completed the syncing process (which consists of three parts: 1. stage + 2. commit w/ a comment + 3. push), you can then open your browser, go to your Github repo, go to the Settings tab, scroll down to GitHub Pages, choose Master branch for your GitHub Pages.

UPDATE: as of October 2020, the default root branch for new repos is named “main” instead of “master.”

Next step: Test Your Site

Go to your url to see if your Github pages site worked.

Nice work!

If you got this working, well done! You just completed a full development cycle of 1) cloning a project from a code source, 2) editing the project locally, then 3) uploading your change to the server. This is not easy, especially for beginners, so go ahead and pat yourself on the back: you now have a local development environment all set up and ready to start coding the website.