If you’re developing on an Apple Silicon Mac (M1, M2, or M3) and experiencing mysterious npm errors, particularly with build tools like Rollup, you might be running into architecture-specific issues. Common symptoms include:

  • Packages failing to install correctly
  • Build tools not finding installed packages
  • Error messages about missing dependencies that are actually installed
  • Issues with global npm packages
  • Errors about architecture compatibility (arm64)

The Root Cause

The core issue often stems from how Node.js and npm are installed. Many developers instinctively use Homebrew to install Node.js, which can lead to problems because:

  1. Homebrew manages one package manager (npm) with another package manager (Homebrew)
  2. Some packages may not be properly compiled for arm64 architecture
  3. Global package installations can conflict with Homebrew’s Node installation

The Solution: Using nvm

Node Version Manager (nvm) provides a much more reliable way to manage Node.js installations, especially on Apple Silicon. Here’s how to fix these issues:

Step 1: Clean Up Existing Installations

bashCopy# Remove Homebrew's node and nvm if installed
brew uninstall node
brew uninstall nvm

# If node refuses to uninstall due to dependencies
brew uninstall --ignore-dependencies node

# Remove nvm directory if it exists
rm -rf ~/.nvm

Step 2: Install nvm Properly

bashCopy# Install nvm using the official installer
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Add nvm configuration to your shell (for zsh)
echo '
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion
' >> ~/.zshrc

# Reload shell configuration
source ~/.zshrc

Step 3: Install Node.js via nvm

bashCopy# Install specific Node version
nvm install 20.18.0  # or whatever version you need

# Set it as default
nvm use 20.18.0

# Verify installation
node -v
npm -v

Step 4: Clean Install Project Dependencies

bashCopy# In your project directory
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

How to Check for Issues

Here are signs that you might need to follow this fix:

  1. Check your Node installation source:
bashCopywhich node  # If it shows /opt/homebrew, you're using Homebrew's version
  1. Check for architecture issues:
bashCopynode -p process.arch  # Should show 'arm64' on Apple Silicon
  1. Check for npm global installation issues:
bashCopynpm list -g --depth=0  # If this shows errors, you might have installation problems

Pro Tips

  1. Always use nvm instead of Homebrew for Node.js installation on Apple Silicon
  2. When installing packages, use npm install --verbose to see detailed progress
  3. Keep packages updated with npm-check-updates: bashCopynpm install -g npm-check-updates ncu -u npm install

Common Error Messages and Solutions

  1. “Cannot find package X imported from Y”
    • Usually means the package isn’t properly installed for your architecture
    • Solution: Clean install via nvm
  2. “Refusing to uninstall node because it is required by X”
    • Use brew uninstall --ignore-dependencies node
    • Reinstall dependent packages after setting up nvm
  3. Architecture-specific errors
    • Look for messages containing “arm64” or “darwin”
    • Usually fixed by clean installation through nvm

Conclusion

While Homebrew is excellent for many development tools, Node.js on Apple Silicon Macs is best managed through nvm. This approach provides better architecture compatibility, easier version management, and fewer conflicts with global packages.

Remember to periodically update your packages and Node.js version, but always test updates in a development environment first.

Further Reading