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)
Visual Studio Code: Your code editor
Node.js LTS: JavaScript runtime for running code outside browsers
Git: Version control system (may already be installed)
Claude Desktop: Arguably the best AI 🤖 tool for coding

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

Claude Desktop:

AI assistant optimized for developers and technical work
Includes a 'learning' mode
Desktop app offers better performance than web version for development tasks
Explains complex technical concepts clearly

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 Claude Desktop

Note: While Claude Desktop is required for the course, you can complete this installation later when Claude functionality becomes necessary for assignments.

Installation Process

Install Claude Desktop via Homebrew:
- In Warp Terminal, execute: brew install --cask claude
- Allow 2-3 minutes for download and installation to complete
Launch Claude Desktop:
- Use Spotlight search (Cmd + Space), type "Claude", press Enter
- Sign in with your existing Claude account or create a new account
- Claude Desktop will appear in your Applications folder for future access
Verify Installation:
- Confirm Claude Desktop appears in Applications folder
- Test access via Spotlight search or direct application launch

Claude Pro Subscription

Course Requirement: Claude Pro is designated as a required expense in place of traditional textbook costs. However, subscription activation can be deferred until Claude functionality is needed for coursework.

Claude Pro Benefits:

Enhanced model performance and processing capabilities
Priority access during high-traffic periods
Increased usage limits for complex computational tasks
Access to latest Claude model releases

Subscription Process:

Navigate to claude.ai
Sign in to your account
Access subscription settings
Select Pro plan ($20/month recommended tier for course requirements)

Cost Consideration: The Pro tier provides sufficient functionality for course needs. Higher tiers are available but represent significant cost increases without substantial additional benefit for academic use.

Step 5: 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 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 6: 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 v24.5.0
- Type: npm --version
- You should see something like 11.5.1
- Both commands should show version numbers

Step 7: 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, skip to Step 7 ⏩👇🏾
- 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.39.5 (Apple Git-154)

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

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 Code
- Navigate into it: cd Code
Test your setup:
- From inside the Code folder, type: code .
- VS Code should open with the Code folder in the sidebar
- You should see "CODE" 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 Code directory in VS Code! 👎🏾

Advanced Concepts & Comparisons

Understanding Homebrew Better

What Homebrew does:

Downloads software from trusted sources. No more clicking 'Agree' in pop-ups!
Keeps everything updated with brew upgrade

Cask vs. Formula:

Formula: Command-line tools (like git, node)
Cask: GUI applications (like visual-studio-code)
Use brew install for formulas, brew install --cask for casks

Useful Homebrew commands:

brew list              # Show installed packages
brew outdated          # Show packages that can be updated
brew upgrade           # Update all packages
brew uninstall package # Remove a package

Essential Terminal commands for Mac:

pwd                    # Print current directory
ls                     # List files and folders
ls -la                 # List with details and hidden files
cd folder-name         # Change to folder
cd ..                  # Go up one level
cd ~                   # Go to home directory
mkdir folder-name      # Create new folder

Understanding Warp Better

Warp is a modern terminal built for speed and efficiency. Here are some key features:

Command Palette: Access commands quickly with Cmd + P.
Split Panes: Work with multiple terminal sessions side by side.
Persistent Sessions: Keep your terminal sessions alive even after closing the window.
Built-in Git Integration: View and manage Git repositories easily.

Even better than reading this, Warp now has a Warp University and YouTube channel with tutorials and resources to help you master the terminal.

Learn the basics of Warp Terminal in this introductory video.

Customize whatever makes sense. You might skip over 2:25-4:05.

Troubleshooting & Best Practices

Common Installation Issues

"Command not found" after installation

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 update through System Preferences
Homebrew: Run brew update && brew upgrade monthly
VS Code: Updates automatically, but check Help → Check for Updates

Organize your development environment:

/Users/YourName/
├── Code/
│   ├── SWIC-Course/     (this course)
│   ├── Practice/        (experiments)
│   └── Projects/        (real projects)
├── Desktop/
└── Documents/

Essential Mac keyboard shortcuts:

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

Security Considerations

When you encounter Gatekeeper warnings or password prompts during installation, it's important to understand the implications. Always ensure that you are downloading software from trusted sources. If you receive a warning, double-check the URL and verify the software's authenticity before proceeding. Keeping your system secure is crucial for a smooth development experience.

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

Wrap-Up & Assessment

Installation Checklist

Check each item as you complete it:

[ ] Warp Terminal opens and shows a prompt
[ ] brew --version shows Homebrew version
[ ] Claude Desktop opens and you can sign in
[ ] 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 ~/Code folder with subfolders
[ ] Can navigate using basic Terminal commands

Quick Test

Run these commands in Terminal to verify everything works:

# Navigate to your Code folder
cd ~/Code

# Check all tools are installed
brew --version
node --version
npm --version
git --version

# Open VS Code from command line
code .

HW: Installation Verification

Open Warp Terminal and run these verification commands to confirm successful installation:

# Check each tool's version
git --version
code --version
node --version
npm --version
gh --version
gh auth status

Each command should return a version number or status confirmation. The spacing between commands and flags (like git --version) is critical. These delimiter spaces allow the terminal to distinguish between the command and its options.

Submit screenshots or a video (no narration needed) to show the output of each command. Ensure the terminal window is large enough to read the text clearly. If any command fails, troubleshoot the installation steps or refer to the troubleshooting section below.

Understanding What You've Built

Your development environment now includes:

Package manager (Homebrew) for easy software installation
Terminal (Warp Terminal) for command line access
AI assistant (Claude Desktop) 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.

Next Steps

With your Mac development environment ready, you'll move on to:

Configure VS Code with essential extensions
Learn Git fundamentals for version control
Write your first JavaScript programs

Congratulations! You now have a professional development environment on Mac. This setup will serve you well throughout your programming journey.

Additional Resources

Homebrew Documentation: https://docs.brew.sh/
VS Code on Mac: https://code.visualstudio.com/docs/setup/mac
Git Documentation: https://git-scm.com/book

Troubleshooting Resources

Homebrew Issues: https://docs.brew.sh/Troubleshooting
VS Code Issues: https://code.visualstudio.com/docs/supporting/troubleshoot
Stack Overflow: Search for "mac development setup" questions

Ready to configure VS Code with essential extensions? Let's move on to the VS Code Configuration lesson.