Setup

This guide will walk you through the steps to set up your project locally and start developing.

Prerequisites

Install these before cloning the repository:

• Node.js 22.21.1, matching the version in package.json
• npm, included with Node.js
• Git
• Docker Desktop or another PostgreSQL 17 installation
• A Resend account for password signups. A verified domain is required before sending to arbitrary recipients, but Resend's test sender can be used with your own account email during initial local setup.

Step 1: Clone the Repository

Clone the project to your local machine:

git clone <your-repo-url> my-saas-app
cd my-saas-app

Step 2: Install Dependencies

We use npm for dependency management:

npm install

Step 3: Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Generate a secret for Better Auth and add it to .env:

You can use the generated value above or create one from your terminal:

openssl rand -base64 32

BETTER_AUTH_SECRET="paste-the-generated-secret-here"

Step 4: Database Setup

1. Make sure you have PostgreSQL running. We provide a docker-compose.yml for convenience:

npm run docker:up

2. The database is automatically created by Docker Compose. If you're using a local PostgreSQL installation, create the database:

createdb database

3. Update DATABASE_URL in .env to match your local setup:

# For Docker (default):
DATABASE_URL="postgresql://postgres:password@localhost:5432/database"

# For local PostgreSQL:
DATABASE_URL="postgresql://your_user:your_password@localhost:5432/database"

4. Apply the migrations committed with the starter kit:

npm run db:migrate

When you later change prisma/schema.prisma, create and apply a development migration with a descriptive name:

npm run db:migrate:dev -- --name describe_your_change

Commit the generated directory in prisma/migrations/ with the schema change. On staging and production, run only npm run db:migrate against the target database. Do not author migrations during deployment.

Step 5: Configure Email

Email verification is required for password signups. Configure RESEND_API_KEY and EMAIL_FROM before creating an account. For the quickest local check, use onboarding@resend.dev as the sender and sign up with the email address attached to your Resend account. Verify a domain before testing other recipients or deploying the application. Follow the email configuration guide to create a Resend API key and verify your sending domain.

Step 6: Start Development Server

npm run dev

Open http://localhost:3000 - your app is running!

Step 7: Create Your First Account

1. Go to http://localhost:3000/auth/sign-up
2. Enter your name, email and password
3. Open the verification email sent through Resend
4. Click the link to verify your email
5. You're in!

Step 8: Verify the Baseline

Before customizing the product, confirm that the repository passes its included quality checks:

npm run typecheck
npm run lint
npm run format
npm run test -- --run

The explicit --run makes Vitest execute once and exit instead of opening its local watch workflow.

Then verify these flows in the browser:

• Create and verify an account
• Create an organization
• Invite a second member if you have another test email
• Open account and organization settings
• Confirm the dashboard loads without server errors

The repository also includes authenticated Playwright coverage for sign-in, organizations, settings, two-factor authentication, AI credit enforcement and the admin area. Point DATABASE_URL at an isolated disposable test database, install the browser once and run the suite:

npm run test:e2e:setup
npm run test:e2e

Step 9: Make Yourself an Admin

The first user should be a platform admin to access the admin dashboard (/dashboard/admin).

Option A: Using Prisma Studio (Recommended)

# Open Prisma Studio
npm run db:studio

1. Open Prisma Studio (usually at http://localhost:5555) in your browser
2. Click on the user table
3. Find your user and click to edit
4. Change role from user to admin
5. Save

Option B: Using SQL directly

# If using Docker (container name may vary based on directory name):
docker compose exec postgres psql -U postgres -d database

# If using local PostgreSQL:
psql -d database

# Then run:
UPDATE "user" SET role = 'admin' WHERE email = 'your@email.com';
\q

Now you can access the admin panel at http://localhost:3000/dashboard/admin.

Next Steps

Keep the verified baseline working while you turn it into your product:

1. Bookmark the common commands used for development, tests and local services.
2. Update the product name, theme and assets using the customization guide.
3. Enable only the providers your product needs in configuration.
4. Add or change the product-specific data model through the Prisma database guide.
5. Complete the production deployment checklist before inviting real users.