Mac Setup Guide

Complete setup instructions for Mac users: Homebrew, VS Code, Node.js, and Git.

Introduction

Welcome Mac Users!

Windows users, head over to the Windows Setup Guide.

Setting up your development environment on Mac is streamlined thanks to Homebrew, the package manager that makes installing developer tools simple and consistent. We'll get you set up with all the essential tools for web development.

Real-world scenario: Mac is the preferred platform for many professional developers because of its Unix-based system and excellent development tools. The setup we're doing today is similar to what you'd do at any tech company on your first day.

What You'll Install Today

Homebrew: Package manager for Mac (like an app store for developer tools)
Warp Terminal: Your primary terminal for this course
Visual Studio Code: Your code editor
Node.js LTS: JavaScript runtime for running code outside browsers
Git: Version control system (may already be installed)
GitHub CLI (gh): Command-line helper for working with GitHub and authentication

Core Concept Overview

What Each Tool Does

Terminal:

Command line interface for interacting with your system
Used to run commands, install software, and manage files
We'll briefly use Mac's built-in Terminal just to bootstrap
Then install Warp Terminal as our permanent development terminal
Warp is superior for development work

Homebrew:

Package manager for macOS
Installs and manages developer tools from the command line
Keeps everything updated and organized
Like having an "App Store" for programming tools

Visual Studio Code (VS Code):

Free, powerful code editor by Microsoft
Excellent for web development
Thousands of extensions available. ⚠️ Be judicious about what you install. For the purposes of this course, we will install only the essential extensions.
Built-in terminal and Git integration

Node.js:

JavaScript runtime that works outside web browsers
Includes npm (Node Package Manager) for installing libraries
LTS (Long Term Support) version for stability

Git:

Version Control System (VCS) for tracking code changes over time
Essential for collaboration and professional development
May already be installed on your Mac

Understanding the Mac Terminal

The Terminal is your gateway to powerful development tools on Mac:

Location: Applications → Utilities → Terminal
Purpose: Run commands, install software, navigate files
Don't worry: We'll guide you through every command. And once Warp is installed, the AI 🤖 will be there for you 🧑🏾‍💻❗

Key Terms

Package Manager: Software that installs and manages other software
Command Line: Text-based interface for running programs
Shell: The program that interprets your Terminal commands and communicates this to your computer
Path: List of directories where the system looks for programs that we try to run from the terminal

Hands-On Application

Step 1: Bootstrap with Mac Terminal

Find Terminal:
- Press Cmd + Space to open Spotlight search
- Type "Terminal" and press Enter
- OR: Go to Applications → Utilities → Terminal
What you'll see:
- A window with white or black background
- Text that looks like: YourName@MacBook-Pro ~ %
- This is called the "prompt" - it's waiting for your commands
Basic orientation:
- The ~ symbol means you're in your home directory. It's about /Users/YourName, where you would ordinarily store your personal files such as Documents, Downloads, etc.
- You can type commands and press Enter to run them
- Don't worry about making mistakes - we'll guide you carefully

Step 2: Install Homebrew

Homebrew will make installing everything else much easier.

Check if Homebrew is already installed:
- In Terminal, type: brew --version
- Press Enter
- If you see a version number, skip to Step 3
- If you get "command not found", continue with installation
Install Homebrew:
- Go to the Homebrew website: https://brew.sh
- Copy the installation command (it's a long line starting with /bin/bash)
- OR use this command (copy and paste exactly):
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Run the installation:
- Paste the command into Terminal
- Press Enter
- You'll see lots of text scrolling by - this is normal
- When prompted for your password, type it (text won't appear as you type - this is normal for security)
- Press Enter after typing password
- Installation takes 5-10 minutes
Follow post-installation instructions:
- After installation, Homebrew will show instructions like:
```
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```
- Copy and paste each line separately, pressing Enter after each
- These commands add Homebrew to your PATH
Verify installation:
- Close Terminal and open it again
- Type: brew --version
- You should see something like "Homebrew 4.x.x"
- If successful, move to next step!

Step 3: Install Warp Terminal

Warp Terminal is an AI powered terminal that you will use over Mac Terminal exclusively. It will make your command line experience more efficient and user-friendly, naturally.

Install Warp Terminal via Homebrew:
- In Terminal, type: brew install --cask warp
- Press Enter
- Wait for download and installation (2-3 minutes)
Open Warp Terminal:
- Press Cmd + Space, type "Warp", press Enter
- Warp Terminal should open with a Welcome screen
- When prompted to sign up for a Warp account, choose "Continue with GitHub" to connect your GitHub account. This gives you access to Warp's cloud features and syncs your settings across devices. If you don't have a GitHub account yet, create one first at github.com.
Close the Standard Terminal:
- Make sure to close the standard Mac Terminal application to avoid confusion.
- Warp Terminal will be your primary terminal moving forward. There is virtually no need to use the standard Terminal ever again.

Note: Henceforth, any references to the Terminal in this course are meant to indicate Warp Terminal.

Step 4: Install Visual Studio Code

Install VS Code via Homebrew:
- In Warp Terminal, type: brew install --cask visual-studio-code
- Press Enter
- Wait for download and installation (2-3 minutes)
Open VS Code:
- Press Cmd + Space, type "Visual Studio Code", press Enter
- OR in Terminal, type: code and press Enter
- VS Code should open with a Welcome screen
Add VS Code to PATH (so you can open it from Warp Terminal):
- In VS Code, press Cmd + Shift + P to open Command Palette. It's a big palette of all the possible things that you would want to do
- Type "shell command"
- Select "Shell Command: Install 'code' command in PATH"
- Click it - you should see "Shell command 'code' successfully installed"
Test the installation:
- In Warp Terminal, navigate to your home directory: cd ~
- Type: code . (the dot means "current folder")
- VS Code should open and show your home folder in the sidebar

Step 5: Install Node.js

Install Node.js LTS via Homebrew:
- In Warp Terminal, type: brew install node
- Press Enter
- Homebrew automatically installs the LTS version
- Wait for download and installation (3-5 minutes)
Verify Node.js installation:
- Type: node --version
- You should see something like v25.2.1
- Type: npm --version
- You should see something like 11.6.4
- Both commands should show version numbers

Step 6: Install or Update Git

Git might already be installed on your Mac, but let's make sure you have the latest version.

Check current Git version:
- In Warp Terminal, type: git --version
- If you see a version number, you can move on to the next step
- If "command not found", Git isn't installed yet 😞
Install Git via Homebrew:
- Type: brew install git
- This will either install Git or update it to the latest version
- Wait for installation to complete
Verify Git installation:
- Type: git --version
- You should see something like git version 2.50.1 (Apple Git-155)

We'll configure Git and set up your name and email in the Git Fundamentals lesson.

Step 7: Install GitHub CLI (`gh`)

GitHub CLI makes it much easier to authenticate with GitHub and create/push repositories from the command line.

Install GitHub CLI with Homebrew:
- In Warp Terminal, type: brew install gh
- Wait for the installation to finish
Verify installation:
- Type: gh --version
- You should see something like gh version 2.x.x
Log in to GitHub (you can do this now or later in the Git lessons):
- Make sure you have a GitHub account and are logged into github.com in your browser
- In Warp Terminal, run:
```
gh auth login
```
- Choose GitHub.com → HTTPS → Login with a web browser
- Copy/paste the one-time code and authorize in your browser
- Back in Warp, run gh auth status to confirm you're logged in

You only need to do this once per machine. Later lessons will reuse this setup when pushing code to GitHub.

Step 8: Set Up Your Development directory

Note: A directory is nothing but a folder on your computer. We will be using the terms interchangeably.

Create a Code directory:
- In Warp Terminal, make sure you're in your home directory: cd ~
- Create the folder: mkdir Dev
- Navigate into it: cd Dev
Test your setup:
- From inside the Dev folder, type: code .
- VS Code should open with the Dev folder in the sidebar
- You should see "DEV" in the sidebar with an empty folder

As we work on stuff, we'll be adding directories for each assignment/project.

*️⃣ ordinarily, you should only type code . to open up a specific directory. We would not normally open up the entire Dev directory in VS Code! 👎🏾

Solution: Close and reopen Warp Terminal
Reason: Terminal needs to reload your PATH
Alternative: Run source ~/.zprofile to reload settings

Permission errors during Homebrew installation

Don't use sudo with Homebrew - it can cause problems
Solution: Make sure you're running the official installation command
If needed: Follow Homebrew's official troubleshooting guide

VS Code won't open from Terminal

Solution: Reinstall the shell command:
- Open VS Code
- Cmd + Shift + P → "Shell Command: Install 'code' command in PATH"

Git asking for credentials repeatedly

Solution: We'll set up proper authentication in the Git lesson
Temporary: This is normal for now

Best Practices for Mac Development

Keep your system updated:

macOS: Regularly install system updates through System Settings.
Homebrew tools (Node, Git, Warp, etc.): At least every 1–2 months, open Warp and run:
```
brew update && brew upgrade
```
Set a recurring reminder on your phone or calendar so this actually happens.
VS Code: Updates automatically, but occasionally check Help → Check for Updates.

Essential Mac keyboard shortcuts:

Cmd + Space → Spotlight search (Find apps quickly)
Cmd + Tab → Switch apps (Navigate between VS Code and Warp Terminal)
Cmd + C/V → Copy/Paste (Works in Warp Terminal too)
Cmd + T → New tab (Multiple Terminal tabs)

Security Considerations

Gatekeeper warnings**:**

Mac may warn about downloaded software
For legitimate tools, click "Open Anyway" in Security Preferences
Homebrew handles this automatically for most tools

Password prompts:

Never enter your password unless you initiated the action
Homebrew installation will ask for password - this is normal
VS Code and Node.js shouldn't need your password
Whenever entering your password, remember that no characters will appear as you type - this is a security feature

Installation Checklist

Check each item as you complete it:

Warp Terminal opens and shows a prompt
brew --version shows Homebrew version
VS Code opens and shows Welcome screen
code . opens current folder in VS Code
node --version shows Node.js version
npm --version shows npm version
git --version shows Git version
Created ~/Dev folder
Can navigate using basic Warp Terminal commands

Quick Test

Run these commands in Warp Terminal to verify everything works:

# Navigate to your Dev folder
cd ~/Dev
# Check all tools are installed
brew --version
node --version
npm --version
git --version
gh --auth status

# Open VS Code from command line
code .

Understanding What You've Built

Your development environment now includes:

Package manager (Homebrew) for easy software installation
Terminal (Warp Terminal) for command line access
Optional AI assistants (like GitHub Copilot in VS Code or Warp's AI) for coding help and learning
Code editor (VS Code) for writing and editing code
JavaScript runtime (Node.js) for running programs outside of a web browser
Version control (Git) for tracking changes
Organized workspace (Code folder) for all your projects

This is the same or similar setup used by professional developers at companies like Apple, Google, and thousands of startups.