How to Set Up macOS for Web Development

Most aspiring front-end developers made mistakes when setting up their development environment. In this guide, you will learn the best practices to prepare macOS for web development.

Like most people, I started my web development journey by learning HTML, CSS, and JavaScript from online tutorials.

There was no roadmaps to tell me what to learn next.

Eventually, I ventured into the land of web frameworks and libraries: Node.js, React, and Vue.js.

I was stuck.

Most tutorials on how to build a project with a framework assume that the readers are familiar with managing computer files through CLI (Command Line Interface) and the concept of package managers.

These tutorials often start by asking you to install a specific package.

As a result, you occasionally encounter issues that require you to run sudo command.

Running sudo command without knowing what it does is a bad idea.¹

Eliminate sudo from your dictionary until you understand the consequences of running it. I ended up wasting countless hours troubleshooting the package and project configurations instead of focusing on the goal: learning to use the framework.

I will show you the tools to set up macOS for web development. Here are topics I’ll cover in this post:

Finder
Xcode Command Line Tools
Git Configuration
1. .gitconfig
2. .gitignore
macOS Package Manager
Version Manager for Programming Language
Dependency Manager
1. Manage Ruby Packages Dependencies with Bundler
2. Manage Python Packages Dependencies with Poetry
More on Package Manager

Finder

Files that start with dot prefix such as .npm don’t show up on Finder by default. Make them visible to see what folders and files are created whenever you install a package or initialize a project.

Run this command in terminal to display hidden files:

defaults write com.apple.finder AppleShowAllFiles TRUE && killall Finder

Terminals, also known as command lines or consoles, allow us to accomplish and automate tasks on a computer without the use of a graphical user interface. Popular macOS terminals are macOS built-in Terminal, iTerm, and Hyper.

Xcode Command Line Tools

You need to install command line tools on macOS separately. With Xcode Command Line Tools, you gain access to useful packages like version control system git and svn.

Install the command line tools by running this command in terminal:

xcode-select —install

You will be prompted with a popup window to install software. Find the detailed tutorial to install Xcode Command Line Tools here.

Git Configuration

Git is the most popular version control system right now. It’s available to you when you installed command line tools earlier.

Before creating your first commit, you have to configure these two files: .gitconfig and .gitignore

You can still follow this guide even if you’re new to Git. There are plenty of online resources that teach Git basic. Check out this interactive introduction to Git.

.gitconfig

Set a global username and email for every repository on your computer. You can learn more about setting up your Git username here, or you can run these commands in terminal.

git config --global user.name "First Last"
git config --global user.email "[email protected]"

Sometimes you want to use a different email address for a separate repository. For example, using your work email address for workplace repositories.

You can set a separate email address in local repository .gitconfig by running the same command without passing the --global option.

git config user.email "[email protected]"

.gitignore

Global .gitignore tells Git what files to ignore whenever you create a new repository. You want to exclude all the hidden files created by macOS by adding these lines into .gitignore file.

# General
.DS_Store
.AppleDouble
.LSOverride

# Icon must end with two \r
Icon

# Thumbnails
._*

# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk

Your .gitignore content will be different based on what projects you’re going to develop often. Browse for more templates here.

macOS Package Manager

Homebrew is the most up to date package manager for macOS. You use it to install and manage packages that are not included with macOS. Paste this into the terminal to install Homebrew:

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

To learn more about it, you can read a practical guide to Homebrew by Flavio.

Version Manager for Programming Language

If you’re going to choose front-end development as a career, you must understand one lesson: You don’t get to choose which version of programing language to work with.

Your local environment setup must match the production environment setup.

For example, macOS Catalina comes with a pre-installed Ruby 2.6.2 by default. If you work for a company that uses Ruby 2.5.0, well, you have to install Ruby 2.5.0 on macOS.

Increase the number of projects, and you see why it’s crucial to have a specific tool to switch the version of your programming language on your local machine.

Version manager lets you install, manage, and switch multiple versions of a programming language easily. It maintains macOS system integrity by installing the programming language at the user directory level.

Each programming language their own environment managers. Regardless of the programming language you’re using, I recommend installing these version managers:

rbenv to manage Ruby.
pyenv to manage Python.
n to manage Node.js.

Enter the command line by line to install each package separately. Make sure to follow the instructions in the console after each complete installation. Some of them require you to add additional configurations in .zshrc or .bash_profile.

brew install rbenv
brew install pyenv
brew install n

The n command installs the package to /usr/local by default. It will ask you to add sudo to execute the command. ** DON’T USE sudo**. Instead, copy and paste the following content to .zshrc or .bash_profile file. If you’re not sure where to find the file, you can type open ~ into the terminal to locate the home folder.

export N_PREFIX=$HOME/.n
export PATH=$N_PREFIX/bin:$PATH

Once the package installations are complete, you should see these configurations in .zshrc.

# n Configurations
export N_PREFIX=$HOME/.n
export PATH=$N_PREFIX/bin:$PATH

# rbenv Configurations
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix [email protected])"
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

# pyenv configuration
eval "$(pyenv init -)"

You can add the configurations above to .zshrc if you don’t see them as part of the content.

Setting Ruby Environment with rbenv

Most people prefer rbenv to rvm for many reasons. If you’re not sure which version manager to use, choose rbenv.

Here’s how to install the latest Ruby version on macOS with rbenv. List all the available versions by running this command:

rbenv install -l

Scroll up to find the latest stable version. You can also google for it. The latest stable version while I work on this post is 2.7.1. Install the selected version with this command:

rbenv install 2.7.1

Wait until the installation is complete. Set the global environment to the latest version by running this command:

rbenv global 2.7.1

To revert back to the system version, run:

rbenv global system

Setting Python Environment with pyenv

I install pyenv because some packages I use are written with Python. You’re also going to need it if you plan to develop using web frameworks like Django, Flask, and CherryPy.

To list all the available versions, run:

pyenv install -l

Find out the latest stable version. To install the latest version of Python with pyenv, run:

pyenv install 3.8

To set the global environment to a specific version, run:

pyenv global 3.8

To revert the global environment back to the system version, run:

pyenv global system

Setting Node.js Environment with `n`

Some of the packages installed on Sublime Text requires node to run. You also need the built-in package manager npm if you plan to develop website with JavaScript framework like Vue.js, Gatsby.js, and Svelte.

To install the latest Node.js, run:

n latest

To switch to other version, for example version 13.0.1, run:

n 13.0.1

It will download and install the requested version if it’s not available locally. Since Node.js is not installed by default. There is no way to set the system version on macOS.

Dependency Manager

Dependency manager can also function as a package manager, but their purpose is more tailored on a per-project basis. Composer’s website explains the difference between dependency and package manager best.

Composer is not a package manager in the same sense as Yum or Apt are. Yes, it deals with “packages” or libraries, but it manages them on a per-project basis, installing them in a directory (e.g. vendor) inside your project. By default it does not install anything globally. Thus, it is a dependency manager. It does however support a “global” project for convenience via the global command.

Here are some advantages of using dependency manager:

It keeps your user (global) library clean from project specific packages.
It lets people run your project easily without messing with their user library.
It separates the project source code from libraries code base by installing the packages in the project directory (local).
It simplifies the process to manage and upgrade the libraries by updating the dependency file: Node.js package.json or Bundler Gemfile.

Manage Ruby Packages Dependencies with Bundler

Bundler is the best way to manage Ruby packages known as gems. It’s important to install Bundler if you want to develop a Jekyll site.

You can learn more about Bundler by following the tutorial on how to start a Jeklyll project from scratch.

Run this command to install Bundler:

gem install bundler

Manage Python Packages Dependencies with Poetry

Poetry is getting more popular these days among Python developers. It’s faster.

You shouldn’t install Poetry with brew install poetry because it can only use the Python environment that comes with Homebrew.

To pair the simplicity of pyenv with poetry, you have to follow the installation instructions on the official site by running this command:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

Verify that Poetry has been installed correctly with this command:

which poetry

If the installation path is correct, you will see something like this:

/Users/<your.macos.username>/.poetry/bin/poetry

More on Package Manager

Package manager is not as relevant as dependency manager because web development is usually project based. You rarely have to install packages globally, but it’s a great way to install useful tools.

Think of package manager as an app store for each language.

Node.js has npm and yarn
Ruby has gem
Python has pip or pip3

For example, I found a Python package called xlsx2csv that can convert xlsx to csv through terminal. I can install it globally by running this command:

pip install xlsx2csv

Instead of installing the package with poetry, I decided to install the package with pip to make the command accessible anytime in console, not restricted to a project.

It makes automation with easier.

You can view all the installed Python packages with this command:

pip list

Another great example is Vue CLI. It’s a command line tool that is built to help you create a new Vue project quickly. You install it by running this command:

npm install -g @vue/cli

By adding -g, you tell npm to install @vue/cli globally. To see the installed modules on your machine, you can run:

npm list -g --depth 0