Quickstart
Get started with the SaaS Boilerplate by installing it via CLI or manually, then setting up your local development environment.
Welcome to the SaaS Boilerplate! This guide will walk you through getting the project up and running on your local machine. Whether you're new to the project or looking to contribute, we'll cover two installation methods: using our CLI tool for a streamlined setup, or manually cloning the repository for more control. By the end, you'll have a fully functional application with a database, authentication, and built-in documentation.
Before You Begin
Ensure you have the following installed on your system:
- Node.js 22+: Required for running the application and its dependencies.
- Docker Desktop: Needed to run PostgreSQL locally for the database.
- Stripe Account (optional): Only if you plan to test billing and payment flows.
Installation
Choose your preferred method to get the SaaS Boilerplate code on your machine. The CLI method is recommended for new projects as it automates much of the initial setup.
The CLI tool simplifies the process by creating a new project directory, installing dependencies, and setting up initial configuration files.
Create a new project
Run the following command in your terminal:
npx saas-boilerplate@latest create my-saas-appReplace my-saas-app with your desired project name. This command will guide you through an interactive setup process.
Follow the CLI prompts
The CLI will ask you a series of questions to configure your project:
What is the name of your project? (Required)? my-app
Choose GitHub authentication method (HTTPS or SSH)? https, ssh
Choose your preferred package manager? npm, yarn, pnpm, bun
Do you want to configure Stripe for payments now? No / Yes
Configure Code Agents (LIA) now? No / Yes
Start the development server now? No / YesIf you prefer more control or want to contribute to the boilerplate itself, clone the repository directly.
Clone the repository
git clone https://github.com/felipebarcelospro/saas-boilerplate
cd saas-boilerplateInstall dependencies
Choose your package manager and run the install command:
npm installpnpm installyarn installThis installs all the required packages, including Next.js, Prisma, Igniter.js, and UI libraries.
Start PostgreSQL with Docker
Launch the local database using Docker Compose:
npm run docker:upThis command starts PostgreSQL and any other services defined in docker-compose.yml, providing a local database instance for development.
Configure environment variables
Copy the sample environment file and customize it for your setup:
cp .env.example .envOpen .env in your editor and fill in the required values. At minimum, set DATABASE_URL to point to your local PostgreSQL instance (usually postgresql://username:password@localhost:5432/database_name). For a full list of environment variables, refer to the Environment Setup guide.
Run database migrations
Apply the database schema to your local PostgreSQL instance:
npm run db:migrate:devThis uses Prisma to create the necessary tables and relationships as defined in prisma/schema.prisma, setting up your database for the application.
Start the development server
Launch the Next.js development server:
npm run devThe application will start at http://localhost:3000. Open this URL in your browser and navigate to http://localhost:3000/docs to explore the built-in documentation.
Optional: Set up Stripe webhooks for billing
If you're working on payment features, start a local Stripe webhook listener in a separate terminal:
npm run stripe:webhookThis allows you to test Stripe events locally. Follow the CLI prompts to configure the webhook endpoint and secret.
Verify Your Setup
To confirm everything is working:
- The app should be accessible at
http://localhost:3000. - Documentation is available at
http://localhost:3000/docs. - Your database is populated with initial tables; run
npm run db:studioto open Prisma Studio and inspect the data.
Troubleshooting
- Database connection issues: Ensure Docker Desktop is running and the
DATABASE_URLin.envmatches the PostgreSQL service indocker-compose.yml. - Missing environment variables: Double-check that you've copied
.env.exampleto.envand filled in all required keys. Next.js will show errors if critical variables are missing. - Stripe webhook errors: Re-run
npm run stripe:webhookand ensure you've set the webhook secret provided by Stripe CLI in your.envfile.