Installation

This guide will walk you through the complete installation process for the Next.js SaaS Boilerplate. Follow these steps carefully to ensure a smooth setup.

System Requirements

📋 Before you start: Make sure your system meets these minimum requirements for optimal performance.

Minimum Requirements

  • Node.js: 18.17.0 or higher
  • pnpm: 8.0.0 or higher (recommended package manager)
  • Git: For cloning the repository
  • PostgreSQL: 14+ (or Supabase account)

Recommended Setup

  • Node.js: 20.x LTS for best compatibility
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 2GB free space for dependencies and development

Step 1: Install Node.js and pnpm

1

Install Node.js

Download and install Node.js from the official website:
# Check if Node.js is installed
node --version

# Should return v18.17.0 or higher
If you need to install or update Node.js:
  • Visit nodejs.org and download the LTS version
  • Or use a version manager like nvm
# Using nvm (recommended)
nvm install --lts
nvm use --lts
2

Install pnpm

This project uses pnpm for faster and more efficient package management:
# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version
✅ Why pnpm? It's faster than npm/yarn, uses less disk space, and has better dependency resolution.

Step 2: Clone the Repository

1

Clone the project

# Clone the repository
git clone <your-repository-url>
cd next-saas-boilerplate

# Verify the project structure

ls -la
You should see the main project files including:
  • package.json
  • src/ directory
  • .env.example
  • drizzle.config.ts
2

Install dependencies

Install all required packages using pnpm:
# Install dependencies (this may take a few minutes)
pnpm install

# Verify installation
pnpm list --depth=0
⚠️ Troubleshooting: If you encounter permission errors, make sure you have write access to the project directory and npm registry.

Step 3: Verify Installation

1

Check TypeScript compilation

Verify that TypeScript can compile the project:
# Check for TypeScript errors
pnpm build

# This should complete without errors
2

Run development server

Start the development server to ensure everything is working:
# Start development server
pnpm dev
You should see output similar to:
▲ Next.js 15.0.0
- Local:        http://localhost:3000
- Environments: .env.local

✓ Ready in 2.3s
3

Access the application

Open your browser and navigate to http://localhost:3000You should see:
  • The landing page loads without errors
  • No console errors in browser developer tools
  • The page shows "Please configure your environment variables" message
💡 Expected behavior: The app will show environment variable warnings until you complete the configuration in the next section.

Troubleshooting Common Issues

Node.js Version Issues

# Error: Node.js version too old
# Solution: Update Node.js to 18.17.0+

nvm install 18
nvm use 18

pnpm Installation Issues

# If pnpm command not found after installation
# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$HOME/.local/share/pnpm:$PATH"

# Then reload your shell
source ~/.zshrc  # or ~/.bashrc

Permission Errors

# If you get EACCES errors
# Fix npm permissions or use a Node version manager

# Option 1: Fix npm permissions (Linux/Mac)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Option 2: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Port Already in Use

# If port 3000 is busy
# Kill the process using port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
pnpm dev -- --port 3001

Build Errors

# If build fails with TypeScript errors
# Clear cache and reinstall
rm -rf node_modules .next
pnpm install
pnpm build

Project Structure Overview

After successful installation, your project structure should look like this: 
next-saas-boilerplate/
├── src/
│   ├── app/                 # Next.js App Router pages
│   ├── components/          # React components
│   ├── db/                  # Database models and scripts
│   ├── lib/                 # Utility functions
│   └── services/            # Business logic layer
├── public/                  # Static assets
├── .env.example            # Environment variables template
├── package.json            # Dependencies and scripts
├── tailwind.config.ts      # Tailwind CSS configuration
├── drizzle.config.ts       # Database configuration
└── next.config.ts          # Next.js configuration

Available Scripts

After installation, you have access to these development scripts : 
pnpm dev          # Start development server
pnpm build        # Build for production
pnpm start        # Start production server
pnpm lint         # Run code linting
pnpm format:fix   # Fix code formatting

Next Steps

🎉 Installation Complete! Your development environment is now ready.
Now that you have successfully installed the boilerplate, continue with:
  1. Environment Variables - Configure your API keys and database connection
  2. Database Setup - Set up and configure your database
  3. First Run - Test your complete setup
💡 Pro tip: Keep the development server running while you configure environment variables. The app will automatically restart when you save changes to .env.local.
    Installation | ShipSaaS Documentation | ShipSaaS - Launch your SaaS with AI in days