Installation

This guide walks you through the complete installation process, from cloning the repository to running your SaaS application locally.

Want to get started fast?

Check out the Quick Start guide for a streamlined 15-minute setup that gets you running immediately.

ℹ️

Prerequisites

Node.js 18+ installed
Git installed
A code editor (VS Code recommended)
Basic familiarity with command line/terminal

Installation Steps

Clone the Repository

Open your terminal and clone the repository to your local machine:

bash

1# Clone the repository
2git clone [your-repository-url] my-saas-app
3 
4# Navigate into the project directory
5cd my-saas-app

💡

Replace [your-repository-url] with the actual URL of your repository. If you received this as a template, use your own repository URL.

Install Dependencies

Install all required dependencies using npm:

bash

1# Install dependencies
2npm install

This will install all the packages defined in package.json, including:

Next.js framework
React and React DOM
TypeScript and type definitions
Tailwind CSS for styling
Prisma ORM for database
Auth.js for authentication
And many other dependencies...

⚠️

Installation Time

The installation may take a few minutes depending on your internet connection and computer speed. This is normal.

Set Up the Database

The project uses a dual database schema system:

SQLite for local development (zero configuration)
PostgreSQL for production

For local development, run the database setup command:

bash

1# Set up SQLite database for local development
2npm run db:dev

This command will:

Generate the Prisma client based on the schema
Create a local SQLite database file (prisma/dev.db)
Apply all database migrations

ℹ️

Automatic Setup

Note: The postinstall script should have already run this automatically after npm install. If the database file already exists, this step may not be necessary.

Create Environment Variables

Create a .env.local file in the project root with the minimum required configuration:

.env.local

1# Database (SQLite for local development)
2DATABASE_URL="file:./dev.db"
3 
4# Auth.js Configuration
5# Generate a secret with: openssl rand -base64 32
6AUTH_SECRET=your_random_secret_here
7 
8# App URL (change port if using a different one)
9AUTH_URL=http://localhost:3000

Generate a secure secret:

bash

1# On macOS/Linux (or Git Bash on Windows)
2openssl rand -base64 32
3 
4# Or use the online generator
5# https://generate-secret.vercel.app/32

Copy the generated string and paste it as the value for AUTH_SECRET.

🚨

Never commit your .env.local file to Git! It should already be in .gitignore by default.

Verify Installation

Start the development server to verify everything is working:

bash

1# Start the development server
2npm run dev

You should see output similar to:

bash

1> next dev
2 
3  ▲ Next.js 16.x.x
4  - Local:        http://localhost:3000
5  - Network:      http://192.168.x.x:3000
6 
7 ✓ Starting...
8 ✓ Ready in 2.4s

Open your browser and navigate to http://localhost:3000. You should see the landing page.

Run Verification Commands

To ensure everything is properly configured, run these verification commands:

bash

1# Check for linting issues
2npm run lint
3 
4# Check TypeScript types
5npm run typecheck
6 
7# Run unit tests
8npm run test:run

All commands should complete successfully without errors.

Project Structure Overview

After installation, your project structure will look like this:

📁my-saas-app

📁prisma/

📁public/

📁src/

📁tests/

📄.env.local

📄.env.example

📄.gitignore

📄next.config.js

📄package.json

📄tsconfig.json

📄vitest.config.ts

Key directories:

prisma/ - Database schema and migrations
src/app/ - Next.js App Router pages
src/components/ - React components
src/lib/ - Utility functions and configurations
tests/ - Unit and E2E tests

Common Installation Issues

Node.js version errors

If you see errors about Node.js version:

bash

1# Check your Node.js version
2node --version
3 
4# Should be v18.x.x or higher
5# If not, download from https://nodejs.org

Port 3000 already in use

If port 3000 is already being used:

bash

1# Use a different port
2PORT=3001 npm run dev
3 
4# Then update AUTH_URL in .env.local:
5AUTH_URL=http://localhost:3001

Database migration fails

If database setup fails:

bash

1# Delete the database file and try again
2rm prisma/dev.db
3npm run db:dev

Next Steps

Now that your application is installed and running:

Configure Environment Variables

Learn about all available configuration options

Set Up Authentication

Configure GitHub and Google OAuth providers

Installation Checklist

Repository cloned successfullyDependencies installed (npm install completed)Database set up (npm run db:dev completed).env.local file created with AUTH_SECRETDev server starts without errors (npm run dev)Landing page loads at http://localhost:3000

Installation Steps

Clone the Repository

Open your terminal and clone the repository to your local machine:

bash

1# Clone the repository
2git clone [your-repository-url] my-saas-app
3 
4# Navigate into the project directory
5cd my-saas-app

💡

Replace [your-repository-url] with the actual URL of your repository. If you received this as a template, use your own repository URL.

Install Dependencies

Install all required dependencies using npm:

bash

1# Install dependencies
2npm install

This will install all the packages defined in package.json, including:

Next.js framework
React and React DOM
TypeScript and type definitions
Tailwind CSS for styling
Prisma ORM for database
Auth.js for authentication
And many other dependencies...

⚠️

Installation Time

The installation may take a few minutes depending on your internet connection and computer speed. This is normal.

Set Up the Database

The project uses a dual database schema system:

SQLite for local development (zero configuration)
PostgreSQL for production

For local development, run the database setup command:

bash

1# Set up SQLite database for local development
2npm run db:dev

This command will:

Generate the Prisma client based on the schema
Create a local SQLite database file (prisma/dev.db)
Apply all database migrations

ℹ️

Automatic Setup

Note: The postinstall script should have already run this automatically after npm install. If the database file already exists, this step may not be necessary.

Create Environment Variables

Create a .env.local file in the project root with the minimum required configuration:

.env.local

1# Database (SQLite for local development)
2DATABASE_URL="file:./dev.db"
3 
4# Auth.js Configuration
5# Generate a secret with: openssl rand -base64 32
6AUTH_SECRET=your_random_secret_here
7 
8# App URL (change port if using a different one)
9AUTH_URL=http://localhost:3000

Generate a secure secret:

bash

1# On macOS/Linux (or Git Bash on Windows)
2openssl rand -base64 32
3 
4# Or use the online generator
5# https://generate-secret.vercel.app/32

Copy the generated string and paste it as the value for AUTH_SECRET.

🚨

Never commit your .env.local file to Git! It should already be in .gitignore by default.

Verify Installation

Start the development server to verify everything is working:

bash

1# Start the development server
2npm run dev

You should see output similar to:

bash

1> next dev
2 
3  ▲ Next.js 16.x.x
4  - Local:        http://localhost:3000
5  - Network:      http://192.168.x.x:3000
6 
7 ✓ Starting...
8 ✓ Ready in 2.4s

Open your browser and navigate to http://localhost:3000. You should see the landing page.

Run Verification Commands

To ensure everything is properly configured, run these verification commands:

bash

1# Check for linting issues
2npm run lint
3 
4# Check TypeScript types
5npm run typecheck
6 
7# Run unit tests
8npm run test:run

All commands should complete successfully without errors.

Project Structure Overview

After installation, your project structure will look like this:

📁my-saas-app

📁prisma/

📁public/

📁src/

📁tests/

📄.env.local

📄.env.example

📄.gitignore

📄next.config.js

📄package.json

📄tsconfig.json

📄vitest.config.ts

Key directories:

prisma/ - Database schema and migrations
src/app/ - Next.js App Router pages
src/components/ - React components
src/lib/ - Utility functions and configurations
tests/ - Unit and E2E tests

Common Installation Issues

Node.js version errors

If you see errors about Node.js version:

bash

1# Check your Node.js version
2node --version
3 
4# Should be v18.x.x or higher
5# If not, download from https://nodejs.org

Port 3000 already in use

If port 3000 is already being used:

bash

1# Use a different port
2PORT=3001 npm run dev
3 
4# Then update AUTH_URL in .env.local:
5AUTH_URL=http://localhost:3001

Database migration fails

If database setup fails:

bash

1# Delete the database file and try again
2rm prisma/dev.db
3npm run db:dev

Prerequisites

Installation Steps

Clone the Repository

Install Dependencies

Installation Time

Set Up the Database

Automatic Setup

Create Environment Variables

Verify Installation

Run Verification Commands

Project Structure Overview

Common Installation Issues

Node.js version errors

Port 3000 already in use

Database migration fails

Next Steps

Configure Environment Variables

Set Up Authentication

Customize Theme Colors

Troubleshooting

Installation Checklist

Installation

Prerequisites

Installation Steps

Clone the Repository

Install Dependencies

Installation Time

Set Up the Database

Automatic Setup

Create Environment Variables

Verify Installation

Run Verification Commands

Project Structure Overview

Common Installation Issues

Node.js version errors

Port 3000 already in use

Database migration fails

Next Steps

Configure Environment Variables

Set Up Authentication

Customize Theme Colors

Troubleshooting

Installation Checklist