Mac Dev Setup

A complete runbook for setting up your new Mac for development. Follow these steps in order to install essential tools, configure your environment, and get ready to code.

1

Install Homebrew

Homebrew is the missing package manager for macOS. It makes installing developer tools simple and keeps them up to date.

Installation

Open Terminal (press ⌘ Space, type "Terminal", press Return) and run:

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

The installer will prompt for your password and explain what it will do. The process takes 5-10 minutes.

Add Homebrew to your PATH

After installation completes, you'll see instructions to add Homebrew to your PATH. For Apple Silicon Macs, run:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

For Intel Macs, Homebrew installs to /usr/local and is already in your PATH.

Verify installation

brew --version

You should see output like Homebrew 4.2.0. If you see "command not found", restart Terminal and try again.

2

Configure Git

Git comes pre-installed on macOS, but you need to configure your identity before making commits.

Set your name and email

Replace the values below with your actual name and email address:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Use the email address associated with your GitHub or GitLab account so your commits are properly attributed.

Set default branch name

Configure Git to use main as the default branch name for new repositories:

git config --global init.defaultBranch main

Enable helpful defaults

git config --global pull.rebase false
git config --global core.autocrlf input

Verify configuration

git config --list --global

Review the output to confirm your name, email, and other settings are correct.

3

Install Node.js

Node.js is required for modern JavaScript development. You can install it directly with Homebrew or use nvm for version management.

Option A: Direct install with Homebrew (recommended for most users)

brew install node

This installs the latest LTS version of Node.js and npm.

Option B: Install with nvm (for managing multiple Node versions)

First, install nvm:

brew install nvm

Add nvm to your shell profile:

mkdir -p ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

Then install Node.js through nvm:

nvm install --lts
nvm use --lts

Verify installation

node --version
npm --version

Both commands should return version numbers. Node should be v20.x or later, npm should be v10.x or later.

4

Generate SSH Keys

SSH keys let you authenticate with GitHub, GitLab, and other services securely without typing your password.

Generate a new SSH key

Replace the email with your GitHub/GitLab email address:

ssh-keygen -t ed25519 -C "your.email@example.com"

When prompted for a file location, press Return to accept the default (~/.ssh/id_ed25519).

Enter a secure passphrase when prompted (recommended), or press Return for no passphrase.

Start the SSH agent

eval "$(ssh-agent -s)"

Add your key to the SSH agent

First, create the SSH config file if it doesn't exist:

touch ~/.ssh/config

Add configuration to automatically load keys:

cat <<EOF >> ~/.ssh/config
Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
EOF

Add your SSH private key to the agent:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Copy your public key

pbcopy < ~/.ssh/id_ed25519.pub

Your public key is now in your clipboard. Add it to GitHub at github.com/settings/keys or GitLab at gitlab.com/-/profile/keys.

Test your connection

ssh -T git@github.com

You should see a message like "Hi username! You've successfully authenticated".

5

Install VS Code

Visual Studio Code is a powerful, free code editor with excellent support for JavaScript, TypeScript, and hundreds of other languages.

Install with Homebrew

brew install --cask visual-studio-code

Install the command line tools

Open VS Code, press ⌘ Shift P to open the command palette, type "shell command", and select "Shell Command: Install 'code' command in PATH".

Now you can open files and folders from Terminal:

code .

Recommended extensions

Install these essential extensions from Terminal:

code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension eamodio.gitlens
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension bradlc.vscode-tailwindcss

Configure settings

Open VS Code settings (⌘ ,) and enable: