Skip to main content

 macOS Installation Guide

This guide will walk you through setting up your development environment on macOS. Please follow each step carefully to ensure a smooth setup process.

🚀 Installation Steps​

1. Homebrew Setup​

Homebrew is the package manager for macOS and will help us install other dependencies:

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

# Add Homebrew to your PATH (for Apple Silicon Macs)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
brew --version

2. Node.js Setup​

We recommend using Node.js version 22.x.x or later. You have two options:

If you prefer a simpler setup:

# Install Node.js using Homebrew
brew install node@22

# Add Node.js to your PATH
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
node --version

Option B: Using NVM​

NVM (Node Version Manager) helps you manage multiple Node.js versions easily:

# Install NVM using Homebrew
brew install nvm

# Add NVM to your shell
mkdir ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"' >> ~/.zshrc
source ~/.zshrc

# Install and use Node.js
nvm install 22
nvm use 22

3. Docker Environment Setup​

Understanding Docker's Role​

Docker is required for running Supabase locally. While this is not a strict requirement, it is recommended to use Docker for local development. You don't need to know Docker to use Supabase, you simply need to have it running to spin up the services locally.

Docker is essential for our development environment because:

  • It runs our Supabase database and related services
  • Ensures consistent development environment across team members
  • Manages multiple services (database, auth, storage) efficiently

Installing Docker​

💡 Development Tip: macOS users can use OrbStack as a lighter alternative to Docker Desktop for better performance.

  1. Install Docker Desktop:

    brew install --cask docker

    or you can directly download from Docker website

  2. Start Docker Desktop:

    • Open Docker Desktop from Applications folder
    • Wait for the Docker engine to start
    • Verify installation: 
      docker --version
      docker-compose --version

  3. Configure Resources (recommended):

    • Open Docker Desktop preferences
    • Go to 'Resources'
    • Allocate at least 4GB of RAM (6GB recommended)
    • Apply & Restart

4. Supabase CLI Installation​

The Supabase CLI allows you to run the entire Supabase stack locally and manage your Supabase projects. For detailed information, refer to the official Supabase CLI documentation.

# Install Supabase CLI
brew install supabase/tap/supabase

# Verify installation
supabase -v

Updating Supabase CLI​

When a new version is released:

# Backup your data first
supabase db dump --local --data-only > backup.sql

# Stop Supabase and update
supabase stop --no-backup
brew upgrade supabase

5. Project Setup​

  1. Clone Repository:

    # Using HTTPS (Recommended)
    git clone https://github.com/themeselection/<OUR_REPO_NAME>.git

    # Or using SSH (if configured)
    git clone git@github.com:themeselection/<OUR_REPO_NAME>.git

    # Navigate to project directory
    cd jetship-nextjs-saas-boilerplate

  2. Set Up Git Remote:

    # Remove existing remote (if any)
    git remote rm origin

    # Add upstream
    git remote add <UPSTREAM> https://github.com/themeselection/<OUR_REPO_NAME>.git

    # Once you have your repository URL, add it as the origin
    git remote add origin <your-repository-url>

    # Keeping your repository up to date
    git pull upstream main

    💡 Why set upstream?

    • Keeps your fork in sync with our main repository
    • Allows you to pull updates and bug fixes
    • Helps manage your custom changes separately

  3. Install Dependencies:

    # Install pnpm if not installed
    brew install pnpm

    # Install project dependencies
    pnpm install

  4. Start Supabase:

    cd apps/web
    pnpm web:supabase:start

    ⚠️ First run may take several minutes to download Docker images

  5. Start Development Server:

    # From project root
    pnpm dev

  6. InBucket Email Server:

    # Access InBucket at
    http://localhost:54324

    💡 Important: InBucket is a test mail server that captures all emails sent during local development. You'll need this for:

    • Testing Supabase Auth emails (signup, password reset, etc.)
    • Viewing transactional emails
    • Debugging email templates

    We recommend bookmarking the InBucket URL as you'll need it frequently during development.

⚡ Performance Tips​

Docker Optimization​

  • Keep Docker Desktop up to date
  • Clean up unused containers and images regularly: 
    docker system prune
  • Monitor resource usage in Docker Desktop

System Maintenance​

  • Use Activity Monitor to track resource usage
  • Clear Docker cache periodically: 
    docker builder prune

🎉 Verification Steps​

  1. Open http://localhost:3000 - Main application
  2. Visit http://localhost:54323 - Supabase Studio
  3. Check Docker Desktop status

Happy Coding! 🚀