Local Setup — Mac macOS

Step 1 — Open Terminal

Terminal is the application where you type commands. To open it:

1. Press Cmd ⌘ + Space to open Spotlight Search.
2. Type Terminal and press Return.
3. A black or white window will open — this is your Terminal.

Step 2 — Install Homebrew (Mac Package Manager)

Homebrew is a free tool that makes installing software on Mac easy. If you already have it, skip this step.

Paste this into Terminal and press Return:

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

After it finishes, if you have an Apple Silicon Mac (M1/M2/M3), run these two extra commands:

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

Verify Homebrew works:

brew --version

You should see something like Homebrew 4.x.x.

Step 3 — Install Git

Git is the tool that tracks code changes and communicates with GitHub.

brew install git

Verify:

git --version

Step 4 — Install Node.js (via nvm)

Node.js is the JavaScript runtime the project needs. We install it via nvm (Node Version Manager) so you can easily switch versions.

brew install nvm

Add nvm to your shell profile:

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

Install Node.js version 20 (the version this project uses):

nvm install 20
nvm use 20
nvm alias default 20

Verify:

node --version   # should print v20.x.x
npm --version

Step 5 — Install pnpm

pnpm is the package manager this project uses (faster than npm). Install it with:

npm install -g pnpm@10

Verify:

pnpm --version   # should print 10.x.x

Step 6 — Set Up Your SSH Key for GitHub

An SSH key lets your computer communicate with GitHub securely without typing your password every time.

Check if you already have one

ls ~/.ssh/id_ed25519_excelcare.pub

If the file exists (no error), skip to Step 6e (add it to GitHub). If it says "No such file or directory", continue from Step 6a.

6a. Generate a new SSH key

ssh-keygen -t ed25519 -C "samson.sam@excelcaregroup.com.au" -f ~/.ssh/id_ed25519_excelcare -N ""

6b. Configure SSH to use this key for GitHub

cat >> ~/.ssh/config << 'EOF'

Host github-excelcare
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_excelcare
  IdentitiesOnly yes
EOF

6c. Copy your public key

cat ~/.ssh/id_ed25519_excelcare.pub

Select all the text that is printed (starts with ssh-ed25519) and copy it.

6d. Add the key to GitHub

1. Go to github.com/settings/ssh/new (logged in as samson.sam@excelcaregroup.com.au).
2. Title: My Mac (or any name you like).
3. Key type: Authentication Key.
4. Paste the key you copied into the Key box.
5. Click Add SSH key.

6e. Test the connection

ssh -T github-excelcare

You should see: Hi samson.sam! You've successfully authenticated...

Step 7 — Clone the Repository

This downloads the code to your computer.

cd ~
mkdir -p github
cd github
git clone git@github-excelcare:Excel-Care-Group/excelcare-webapp.git
cd excelcare-webapp

You should now see a folder called excelcare-webapp on your computer.

Step 8 — Configure Git Identity

Tell Git your name and email so your changes are labelled correctly:

git config --global user.name "Your Name"
git config --global user.email "samson.sam@excelcaregroup.com.au"

Set the remote to use the SSH alias:

cd ~/github/excelcare-webapp
git remote set-url origin git@github-excelcare:Excel-Care-Group/excelcare-webapp.git

Step 9 — Install Project Dependencies

Inside the project folder, run:

cd ~/github/excelcare-webapp
pnpm install

This downloads all the libraries the website needs. It may take 1–3 minutes.

Also install the Cloud Functions dependencies:

npm --prefix functions install

Step 10 — Set Up Environment Variables

The project needs a .env file for local configuration. Create it from the example:

cp .env.example .env

Step 11 — Install a Code Editor (Recommended: VS Code)

Visual Studio Code is a free, beginner-friendly code editor.

1. Go to code.visualstudio.com and click Download for Mac.
2. Open the downloaded .zip file, then drag Visual Studio Code to your Applications folder.
3. Open VS Code, then open the project: File → Open Folder → navigate to ~/github/excelcare-webapp.

Step 12 — Run the Website Locally

In Terminal, make sure you are in the project folder, then run:

cd ~/github/excelcare-webapp
pnpm dev

You should see output like:

  VITE v7.x.x  ready in 800ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.x.x:5173/

1. Open your browser and go to http://localhost:5173.
2. You should see the ExcelCare website running on your computer.
3. Any changes you save in VS Code will automatically refresh the browser — this is called hot reload.
4. To stop the local server, press Ctrl + C in Terminal.

Troubleshooting