macOS Development Environment Setup Guide

01

Introduction

If you're taking the curso.dev (or any web development course) and use a Mac, you're in luck — macOS is a Unix-based system, which means most developer tools work natively without the extra layer that Windows requires (like WSL).

This guide mirrors the structure of the curso.dev Windows environment setup lesson, but adapted entirely for macOS. By the end, you'll have a professional terminal, Git, Node.js, VS Code, and everything you need to start coding.

💡

This guide was written for macOS Ventura (13) and newer, including Apple Silicon (M1/M2/M3/M4) and Intel Macs.

02

Installing Xcode Command Line Tools

On Windows you'd start by enabling WSL. On macOS, the equivalent first step is installing Xcode Command Line Tools. This gives you essential developer tools like git, make, clang, and compilers — without needing to download the full Xcode IDE (which is ~12 GB).

Open Terminal (press ⌘ + Space, type "Terminal", hit Enter) and run:

Terminalxcode-select --install

A popup will appear asking to install the tools. Click Install and wait a few minutes. To verify it worked:

xcode-select -p
# Expected output: /Library/Developer/CommandLineTools

03

Installing Homebrew (Package Manager)

On Windows, the tutorial uses Chocolatey or Winget to install programs from the command line. On macOS, the equivalent is Homebrew — the most popular package manager for Mac. It lets you install almost anything with a single command.

Install Homebrew by running:

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

After installation, pay attention to the output — on Apple Silicon Macs, Homebrew installs to /opt/homebrew and you may need to add it to your PATH. The installer will show you the exact commands. Usually something like:

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

Verify the installation:

brew --version
# Homebrew 4.x.x

✅

From now on, you can install almost anything with brew install <package> for CLI tools or brew install --cask <app> for GUI applications. A partir de agora, você pode instalar quase tudo com brew install <pacote> para ferramentas CLI ou brew install --cask <app> para aplicações com interface gráfica.

04

Choosing Your Terminal (iTerm2)

On Windows, you'd install Windows Terminal. macOS already comes with a decent Terminal app, but iTerm2 is a massive upgrade: split panes, search, hotkey window, profiles, and much better customization.

Install it with Homebrew:

brew install --cask iterm2

Open iTerm2 and start using it as your default terminal from now on. You can configure keyboard shortcuts, appearance, and window behavior under iTerm2 → Settings (or ⌘ + ,).

🖥️

Alternative: If you prefer a more minimal and GPU-accelerated terminal, check out Warp (brew install --cask warp) or Alacritty (brew install --cask alacritty). Alternativa: Se preferir um terminal mais minimalista e acelerado por GPU, veja o Warp (brew install --cask warp) ou Alacritty (brew install --cask alacritty).

05

Configuring Zsh (already your default shell)

On Windows, you'd need to install Zsh inside WSL/Ubuntu. Great news: macOS has shipped Zsh as the default shell since Catalina (2019). You already have it!

Verify it:

echo $SHELL
# /bin/zsh

zsh --version
# zsh 5.9 (or similar)

Your Zsh configuration lives in ~/.zshrc. This is the file we'll be editing throughout this guide to add plugins, aliases, themes, and environment variables.

06

Installing Oh My Zsh

Oh My Zsh is a framework for managing your Zsh configuration. It comes with hundreds of plugins, themes, and helpers that make the terminal experience much more productive and enjoyable.

Terminalsh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

After installation, your ~/.zshrc will be automatically configured with Oh My Zsh. Restart your terminal or run source ~/.zshrc to apply changes.

07

Customizing Your Terminal Theme

The default Oh My Zsh theme is robbyrussell. Let's install something more powerful: Powerlevel10k — it shows Git status, current directory, Node version, and more in a beautiful, fast prompt.

Step 1: Install a Nerd Font

Powerlevel10k uses special icons that require a patched font:

brew install --cask font-meslo-lg-nerd-font

Then set MesloLGS Nerd Font as the font in your terminal: in iTerm2 go to Settings → Profiles → Text → Font.

Step 2: Install Powerlevel10k

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Step 3: Activate the theme

Edit your ~/.zshrc and change the theme line:

~/.zshrcZSH_THEME="powerlevel10k/powerlevel10k"

Restart your terminal, and the Powerlevel10k configuration wizard will start automatically. Follow the prompts to choose your preferred style.

08

Essential Zsh Plugins

The Windows tutorial covers the auto-suggestions plugin. Let's install that plus syntax highlighting — both are game-changers.

zsh-autosuggestions

Suggests commands as you type, based on your history:

git clone https://github.com/zsh-users/zsh-autosuggestions \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

zsh-syntax-highlighting

Colors your commands green (valid) or red (invalid) as you type:

git clone https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

Now enable both in ~/.zshrc by editing the plugins line:

~/.zshrcplugins=(git zsh-autosuggestions zsh-syntax-highlighting)

Apply the changes:

source ~/.zshrc

09

Navigating Directories in the Terminal

Here are the essential commands for moving around. These are the same on macOS as they are in WSL/Linux:

# Show current directory
pwd

# List files and folders
ls          # basic list
ls -la      # detailed list with hidden files

# Move between directories
cd ~                  # go to your home directory
cd Documents          # enter a folder
cd ..                 # go up one level
cd -                  # go to previous directory
cd ~/Projects         # go to an absolute path

# Create directories
mkdir my-project              # create a single folder
mkdir -p projects/web/app     # create nested folders

⚡

With zsh-autosuggestions installed, press → (right arrow) to accept a suggestion as you type a command. Com o zsh-autosuggestions instalado, pressione → (seta direita) para aceitar uma sugestão enquanto digita um comando.

10

Text Editors in the Terminal

You'll often need to edit config files directly in the terminal. macOS comes with vim and nano pre-installed.

nano is the easiest for beginners — it shows keyboard shortcuts at the bottom of the screen:

# Edit a file with nano
nano ~/.zshrc

# Save: Ctrl + O then Enter
# Exit: Ctrl + X

If you want a more modern terminal editor, install Neovim:

brew install neovim

11

Creating Aliases

Aliases are shortcuts for long commands. Add them to the bottom of your ~/.zshrc:

~/.zshrc# Navigation
alias ..="cd .."
alias ...="cd ../.."
alias ll="ls -la"
alias projects="cd ~/Projects"

# Git shortcuts
alias gs="git status"
alias ga="git add ."
alias gc="git commit -m"
alias gp="git push"
alias gl="git log --oneline --graph"

# Quick edit config
alias zshconfig="code ~/.zshrc"

Apply the changes:

source ~/.zshrc

12

Creating SSH Keys

SSH keys let you authenticate with services like GitHub without typing your password every time. Generate a key pair:

ssh-keygen -t ed25519 -C "your_email@example.com"

Press Enter to accept the default file location, then set a passphrase (or leave empty).

Add the key to the SSH agent so you don't have to enter the passphrase every time:

# Start the SSH agent
eval "$(ssh-agent -s)"

# On macOS, add to Keychain so it persists across reboots
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Configure SSH to always use the Keychain. Create or edit ~/.ssh/config:

~/.ssh/configHost github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Copy your public key to add it to GitHub:

pbcopy < ~/.ssh/id_ed25519.pub
# Your public key is now in the clipboard!

Go to GitHub → Settings → SSH and GPG keys → New SSH key, paste it there, and save.

🍎

pbcopy is a macOS-exclusive command that copies text to the clipboard. On Linux you'd use xclip — this is one of those nice macOS conveniences! pbcopy é um comando exclusivo do macOS que copia texto para a área de transferência. No Linux você usaria xclip — uma dessas conveniências legais do macOS!

13

Configuring Git

Git comes pre-installed with Xcode Command Line Tools. Set your identity:

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

# Set VS Code as the default editor
git config --global core.editor "code --wait"

# Set 'main' as the default branch name
git config --global init.defaultBranch main

Verify your configuration:

git config --list

14

Installing NVM and Node.js

Just like in the Windows tutorial, we'll use NVM (Node Version Manager) to install and manage Node.js versions. Never install Node directly — NVM lets you switch between versions easily.

Terminalcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Restart your terminal (or run source ~/.zshrc), then install Node.js:

# Install the latest LTS version
nvm install --lts

# Verify installation
node --version
npm --version

# Set it as the default
nvm alias default node

⚠️

If nvm is not found after installation, make sure these lines exist in your ~/.zshrc:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" Se nvm não for encontrado após a instalação, confirme que estas linhas existem no seu ~/.zshrc:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

15

Installing VS Code

Visual Studio Code is the most popular code editor. Install it with Homebrew:

brew install --cask visual-studio-code

Enable the `code` command in terminal

Open VS Code, press ⌘ + Shift + P, type "Shell Command: Install 'code' command in PATH", and press Enter. Now you can open any folder:

# Open current folder in VS Code
code .

# Open a specific project
code ~/Projects/my-app

Recommended extensions

Install these to enhance your experience: ESLint, Prettier, GitLens, Material Icon Theme, and the One Dark Pro or Dracula theme.

16

Running a Node.js Project

Let's verify everything works by creating and running a simple project:

# Create a project folder
mkdir ~/Projects/hello-node && cd ~/Projects/hello-node

# Initialize the project
npm init -y

# Create the main file
echo 'console.log("🎉 Hello from macOS! Everything is working.")' > index.js

# Run it
node index.js

If you see the message printed in the terminal, your environment is 100% ready!

Cloning and running an existing project

This is how you'd typically start with a real project (like the TabNews from curso.dev):

# Clone a repository
git clone git@github.com:username/project-name.git

# Enter the project folder
cd project-name

# Install dependencies
npm install

# Run the development server
npm run dev

17

Bonus: Installing Docker

Docker lets you run services like databases in isolated containers. On macOS, the simplest approach is Docker Desktop:

brew install --cask docker

Open Docker Desktop from your Applications folder. It will run in the background. Verify:

docker --version
docker compose version

🐳

Lightweight alternative: If Docker Desktop feels heavy, try OrbStack (brew install --cask orbstack) — it's much faster and lighter on Apple Silicon Macs. Alternativa leve: Se o Docker Desktop parecer pesado, experimente o OrbStack (brew install --cask orbstack) — é muito mais rápido e leve em Macs com Apple Silicon.

18

Conclusion

That's it! Here's a quick summary of everything you've set up:

Xcode CLI Tools → essential compilers and developer tools. Homebrew → package manager (your new best friend). iTerm2 → a professional terminal. Zsh + Oh My Zsh + Powerlevel10k → a beautiful, productive shell. Plugins → auto-suggestions and syntax highlighting. SSH Keys → secure authentication with GitHub. Git → version control, properly configured. NVM + Node.js → JavaScript runtime with version management. VS Code → the code editor, with terminal integration. Docker → containerized services for development.

Your Mac is now a professional-grade development machine. Happy coding! 🚀

📖

This guide was inspired by the Development Environment lesson from curso.dev by Filipe Deschamps, adapted for macOS users.

Setting Up Your
Development Environment
on macOS

Introduction

Installing Xcode Command Line Tools

Installing Homebrew (Package Manager)

Choosing Your Terminal (iTerm2)

Configuring Zsh (already your default shell)

Installing Oh My Zsh

Customizing Your Terminal Theme

Step 1: Install a Nerd Font

Passo 1: Instale uma Nerd Font

Step 2: Install Powerlevel10k

Passo 2: Instale o Powerlevel10k

Step 3: Activate the theme

Passo 3: Ative o tema

Essential Zsh Plugins

zsh-autosuggestions

zsh-autosuggestions

zsh-syntax-highlighting

zsh-syntax-highlighting

Navigating Directories in the Terminal

Text Editors in the Terminal

Creating Aliases

Creating SSH Keys

Configuring Git

Installing NVM and Node.js

Installing VS Code

Enable the `code` command in terminal

Habilite o comando `code` no terminal

Recommended extensions

Extensões recomendadas

Running a Node.js Project

Cloning and running an existing project

Clonando e rodando um projeto existente

Bonus: Installing Docker

Conclusion

Introduction

Installing Xcode Command Line Tools

Installing Homebrew (Package Manager)

Choosing Your Terminal (iTerm2)

Configuring Zsh (already your default shell)

Installing Oh My Zsh

Customizing Your Terminal Theme

Step 1: Install a Nerd Font

Passo 1: Instale uma Nerd Font

Step 2: Install Powerlevel10k

Passo 2: Instale o Powerlevel10k

Step 3: Activate the theme

Passo 3: Ative o tema

Essential Zsh Plugins

zsh-autosuggestions

zsh-autosuggestions

zsh-syntax-highlighting

zsh-syntax-highlighting

Navigating Directories in the Terminal

Text Editors in the Terminal

Creating Aliases

Creating SSH Keys

Configuring Git

Installing NVM and Node.js

Installing VS Code

Enable the code command in terminal

Habilite o comando code no terminal

Recommended extensions

Extensões recomendadas

Running a Node.js Project

Cloning and running an existing project

Clonando e rodando um projeto existente

Bonus: Installing Docker

Conclusion

Enable the `code` command in terminal

Habilite o comando `code` no terminal