Mac Development Environment Setup

A comprehensive, idempotent bash script designed to set up a complete development environment on macOS for TypeScript microservices development.

Purpose

This script automates the installation and configuration of essential development tools, IDEs, databases, containerization tools, and terminal enhancements for modern web development. It's specifically tailored for developers working with:

• TypeScript/JavaScript microservices
• Node.js applications
• Docker containerization
• Database development (PostgreSQL, MongoDB, MySQL)
• Modern terminal workflows

Prerequisites

• macOS (any recent version)
• Internet connection for downloading packages
• Administrator privileges (for installing system packages)
• Fresh macOS installation or willingness to install/update existing tools

How to Run

Quick Start

# Clone or download the script
curl -O https://raw.githubusercontent.com/your-repo/setup-mac4dev.sh

# Make it executable
chmod +x setup-mac4dev.sh

# Run the script
./setup-mac4dev.sh

Alternative: Direct Execution

# Run directly without downloading
bash <(curl -fsSL https://raw.githubusercontent.com/your-repo/setup-mac4dev.sh)

Safety Features

• Idempotent: Safe to run multiple times
• Backup creation: Existing configurations are backed up before modification
• Error handling: Script exits on errors with clear messages
• OS validation: Only runs on macOS

What Gets Installed

🏠 Package Management

• Homebrew - macOS package manager
• NVM - Node Version Manager for Node.js version control

💻 Development Tools

• Git - Version control
• Node.js LTS - JavaScript runtime
• pnpm & yarn - Alternative package managers
• Python 3.11 - For Neovim and language servers

🎨 Code Editors & IDEs

• Visual Studio Code - Primary IDE
• Cursor - AI-powered IDE
• Neovim + AstroNvim - Terminal-based IDE with modern features

🐳 Containerization

• OrbStack - Lightweight Docker Desktop alternative
• Docker CLI tools - docker, docker-compose, docker-buildx

🗄️ Database Tools

• TablePlus - Universal database client
• DBeaver Community - Free database client
• MongoDB Compass - Official MongoDB GUI
• CLI tools: pgcli, mycli, mongosh

🌐 Browsers

• Brave Browser - Privacy-focused browser
• Google Chrome - Standard browser
• Firefox - Alternative browser

💬 Communication

• Slack - Team communication
• Zoom - Video conferencing

🖥️ Terminal & Shell

• iTerm2 - Enhanced terminal
• Zsh with plugins - Modern shell with autosuggestions, syntax highlighting
• Starship - Cross-shell prompt
• Nerd Fonts - Programming fonts with icons

🔧 Development Utilities

• API Testing: Postman, Insomnia
• Version Control GUI: SourceTree
• Modern CLI tools: bat, ripgrep, fd, fzf, htop
• Kubernetes tools: kubectl, helm, kubectx
• Cloud CLIs: AWS CLI, Azure CLI

📦 VS Code Extensions

The script installs 20+ essential extensions including:

• TypeScript/JavaScript support
• ESLint, Prettier
• Git integration (GitLens)
• Docker support
• Database tools
• Popular themes (Material, Dracula, GitHub, etc.)

Configuration Details

Shell Configuration

• Zsh with modern plugins (autosuggestions, syntax highlighting, completions)
• Starship prompt with git status, Node.js version, Docker context
• Development aliases for common commands
• NVM integration for Node.js version management

Neovim Setup

• AstroNvim distribution with TypeScript-optimized configuration
• Language servers for TypeScript, ESLint, HTML, CSS, JSON, YAML
• Tree-sitter for enhanced syntax highlighting
• LSP integration with auto-formatting on save

Git Configuration

• Prompts for username and email if not configured
• Sets VS Code as default editor
• Configures main as default branch

Potential Issues & Troubleshooting

⚠️ Important Warnings:

• Starship Configuration: The script's Starship configuration may fail in some environments. If your prompt doesn't display correctly, use the manual setup commands below.
• AstroNvim Plugins: Some AstroNvim plugins may encounter installation issues, especially on first launch. This is normal and can be resolved with the troubleshooting steps below.

Common Issues

1. Homebrew Installation Fails

# If Homebrew installation fails, try:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. VS Code Extensions Not Installing

• Cause: VS Code CLI not available immediately after installation
• Solution: Run the script again after opening VS Code once, or install manually

3. NVM Not Loading in New Terminal

# Add to ~/.zshrc if missing:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

4. OrbStack Setup Required

• Issue: OrbStack needs manual setup after installation
• Solution: Launch OrbStack from Applications folder to complete Docker setup

5. Permission Issues

# If you get permission errors:
sudo chown -R $(whoami) /usr/local/share/zsh

6. Starship Configuration Failure

• Issue: Starship prompt may not display correctly due to configuration issues
• Solution: If automatic configuration fails, manually configure Starship:

  # Add to ~/.zshrc
  eval "$(starship init zsh)"
  
  # Or reset to default configuration
  starship preset default > ~/.config/starship.toml

• Reference: Starship Installation Guide

7. AstroNvim Plugin Installation Issues

• Issue: Some plugins may fail to install or function incorrectly
• Common Problems:
  • Missing dependencies (e.g., ripgrep for search functionality)
  • Language servers not installing properly
  • Tree-sitter parsers failing to load
• Solutions:

  # Install missing dependencies
  brew install ripgrep lazygit gdu bottom tree-sitter
  
  # In Neovim, check health and install missing components
  :checkhealth
  :Lazy sync
  :TSInstall <language>  # e.g., :TSInstall typescript

• Reference: AstroNvim FAQ and Getting Started Guide

8. Neovim Plugin Installation Slow

• Expected: First launch takes 5-10 minutes to install plugins
• Solution: Be patient, or run :Lazy sync in Neovim

Network Issues

• Slow downloads: Some packages are large (VS Code, browsers)
• Timeout errors: Retry the script or install packages individually

Disk Space

• Requirement: ~10-15GB free space
• Large packages: VS Code, browsers, Docker images

Expected Outcome

After successful completion, you'll have:

✅ Complete Development Environment

• Modern terminal with enhanced productivity features
• Multiple code editors configured for TypeScript development
• Containerization tools ready for microservices
• Database clients for all major databases

✅ Optimized Workflow

• Git configured with your credentials
• Development aliases for common tasks
• Node.js version management via NVM
• Auto-formatting and linting in editors

✅ Professional Setup

• Consistent theming across tools
• Language servers for intelligent code completion
• Modern CLI tools replacing legacy ones
• Cloud and Kubernetes tools for deployment

Next Steps After Installation

1. Restart Terminal: source ~/.zshrc or open new terminal
2. Configure iTerm2: Set font to 'FiraCode Nerd Font Mono'
3. Launch OrbStack: Complete Docker setup from Applications
4. Verify Extensions: Open VS Code/Cursor to check extensions
5. Test Neovim: Run nvim - plugins will auto-install
6. Install Node Versions: Use nvm install <version> as needed

Useful Commands After Setup

# Development shortcuts
nvim                    # Open Neovim with AstroNvim
code .                  # Open current directory in VS Code
cursor .                # Open current directory in Cursor
dc up                   # Docker Compose up
pgcli                   # Enhanced PostgreSQL CLI
lazygit                 # Git TUI

# Node.js management
nvm use 18              # Switch to Node 18
nvm install 20          # Install Node 20
npx typescript          # Run TypeScript without global install

# Modern CLI tools
bat file.txt            # Better cat
rg "pattern"            # Better grep
fd "name"               # Better find

AstroNvim Quick Reference

• Leader key: <Space>
• Find files: <Space>ff
• Find word: <Space>fw
• File explorer: <Space>e
• LazyGit: <Space>gg
• Documentation: https://docs.astronvim.com

Support

If you encounter issues:

1. Check the troubleshooting section above
2. Ensure you have sufficient disk space and internet connection
3. Try running the script again (it's idempotent)
4. Check the script logs for specific error messages

License

This script is provided as-is for educational and development purposes. Use at your own discretion and always review scripts before execution.

---

Happy coding! 🚀