Setup and Configuration for Makerkit Next.js Prisma

In this module, you'll get Makerkit running locally and configure it for a B2B SaaS application. This is hands-on - by the end, you'll have a working app.

Time: ~30 minutes

What you'll accomplish:

• Install and run Makerkit locally
• Verify everything works
• Configure for B2B (organizations-only mode)
• Understand the project structure

Prerequisites

Recommended: Read Module 0: Architecture & Technologies first to understand the stack at a high level.

Before starting, ensure you have:

• Node.js 20.10.0+ - Check with node --version
• pnpm 10+ - Install with npm install -g pnpm@latest
• Docker - For local PostgreSQL and email testing
• Git - For version control

For a more detailed list of prerequisites, please refer to the Prerequisites Documentation.

Step 1: Clone and Install

The first step is to clone the repository from Github and install the dependencies. Make sure to have a valid Makerkit license and that you have your Github account configured with SSH.

# Clone the repository
git clone git@github.com:makerkit/next-prisma-saas-kit-turbo teampulse
# Move into the project directory
cd teampulse
# Install all dependencies
pnpm install

Note: When you create your own project, replace "teampulse" with the name of your project.

This installs dependencies for the entire monorepo. It takes a minute or two.

Setting up your Project

Before you start, please run the following script to initialize the project:

pnpm turbo gen setup

Please follow the prompts to set up your project. The command will guide you through initial configuration.

Step 2: Start the Database

Makerkit provides a Docker Compose file to run PostgreSQL and Mailpit (for email testing) locally.

Before starting the database, please make sure to have Docker installed and running.

# Start PostgreSQL + Mailpit containers
pnpm run compose:dev:up

This starts Supabase services including:

• PostgreSQL (via Supabase) on port 54322 (direct) or accessible via Supabase API on port 54321
• Mailpit (email viewer) on port 8025

To shut down the containers, run the following command:

pnpm run compose:dev:down

If you have multiple projects running, you can update the container names to avoid conflicts. For example, for this project, we would update the docker-compose.dev.yml file to the following:

services:
  postgres:
    image: postgres:17
    container_name: teampulse-postgres
  mailpit:
    image: mailpit/mailpit
    container_name: teampulse-mailpit

This allows me to run multiple projects locally without conflicts.

Step 3: Understanding Environment Files

Makerkit uses multiple .env files with a specific precedence (highest to lowest). This is a built-in feature of Next.js that allows you to have different environment variables for different environments.

• Add secrets to .env.local (never committed)
• .env.development contains non-sensitive dev defaults and is committed to the repo
• Next.js automatically loads these based on the environment

For a more detailed explanation of the environment files, please refer to the Environment Variables Documentation.

Step 4: Initialize the Database

First, generate the Prisma client:

pnpm --filter @kit/database prisma:generate

Then apply the database migrations:

pnpm --filter @kit/database prisma:migrate

This creates all the tables Makerkit needs (users, organizations, sessions, etc.).

Optional: Seed test data

pnpm seed

This creates test users you can sign in with:

• Super admin: admin1@makerkit.dev / testingpassword (can access /admin)
• Regular users: user1@makerkit.dev through user5@makerkit.dev / testingpassword

The command will output some credentials you can use to sign in.

Step 5: Start the Development Server

Now, we can finally start the Next.js development server by running the following command:

pnpm dev

Open http://localhost:3000 in your browser.

You should see the landing page!

Checkpoint: Verify It Works

Before continuing, verify:

• [ ] Landing page loads at http://localhost:3000
• [ ] Can access sign up at http://localhost:3000/auth/sign-up
• [ ] Can access sign in at http://localhost:3000/auth/sign-in
• [ ] Mailpit is accessible at http://localhost:8025

Test the full flow:

1. Go to /auth/sign-up
2. Create an account with your email
3. Check Mailpit at http://localhost:8025 for the verification email
4. Click the verification link
5. You should land on the dashboard

If you seeded test data, you can also sign in directly with user1@makerkit.dev / testingpassword.

Step 6: Configure for B2B

By default, Makerkit runs in "hybrid" mode (personal accounts + organizations). For a B2B SaaS, you want organizations-only mode.

Edit apps/web/.env.local:

# Set to organizations-only for B2B
NEXT_PUBLIC_ACCOUNT_MODE=organizations-only

The Dev server should pick up the changes automatically.

What changes:

• Users must belong to an organization
• Organization is auto-created on sign-up
• No personal account context
• Account switcher only shows organizations

Test it: Sign up with a new email. You'll be automatically placed in a new organization named after you.

Understanding the Structure

Now that it's running, let's understand what you have.

Monorepo Layout

next-postgres-saas-kit-turbo/
├── apps/
│   ├── web/                 # Main Next.js app (you'll work here most)
│   │   ├── app/            # Pages and routes
│   │   ├── config/         # Configuration files
│   │   └── .env.local      # Your local environment
│   └── e2e/                 # Playwright tests
├── packages/
│   ├── database/           # Prisma schema & migrations
│   ├── better-auth/        # Authentication
│   ├── ui/                  # UI components (shadcn-based)
│   ├── rbac/               # Roles & permissions
│   └── ...                  # 24+ feature packages (billing, email, admin, etc.)
└── docker-compose.dev.yml   # Local development services

Key Configuration Files

Account Modes

Makerkit supports three modes:

We configured organizations-only for our B2B SaaS application.

Module 1 Complete!

You now have:

• [x] Makerkit running locally
• [x] Database connected and initialized
• [x] Email testing with Mailpit
• [x] Configured for B2B (organizations-only)
• [x] Understanding of project structure

Next: In Module 2, you'll customize the branding of your application and make it truly your own.

Next: Branding