Installation

Get your development environment up and running with this step-by-step installation guide.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js - ^20.19.0, ^22.12.0, or >=24.0.0 (Node 24 recommended; matches Docker/CI examples) (Download)
• PNPM - Version 9.x or higher (Install guide)
• PostgreSQL - Local or remote database connection string (Download)
• Git - For version control (Download)

Download the boilerplate

After purchasing your license, download the boilerplate:

1. Visit the download page - Go to the download page of Rapidstack
2. Enter your license key - Use the license key you received after purchase
3. Download the zip file - The boilerplate will download as a zip file
4. Extract and navigate - Extract the zip file and navigate to the directory

unzip rapidstack-nuxt4.zip
cd rapidstack-nuxt4

Install dependencies

Install all project dependencies using PNPM:

pnpm install

This will install all required packages including Nuxt 4, Prisma, Stripe, authentication libraries, and more. The postinstall script also runs prisma generate so the generated Prisma client is ready for local development.

Set up environment variables

Create a .env file in the root directory. You can start by copying the example file:

cp .env.example .env

Then, edit .env with your configuration. At minimum, you'll need the Database connection string and Site configuration.

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/myapp"

# Site configuration
NUXT_PUBLIC_SITE_URL="http://localhost:3000"
NUXT_PUBLIC_SITE_NAME="Your App Name"
NUXT_PUBLIC_SITE_DOMAIN="localhost"

# Email (Resend)
RESEND_API_KEY="re_..."

# Stripe payments
STRIPE_SECRET_KEY="sk_test_..."
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

Set up the database

Create your database

You'll need a PostgreSQL database. You can either:

• Use a local PostgreSQL instance - Create a database locally.
• Use a hosted database - Services like Supabase, Neon, or Railway.

If using a local database, create it:

createdb myapp

DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/myapp"

Run migrations

Run Prisma migrations to set up your database schema:

pnpm prisma migrate dev

This creates all necessary tables including users, sessions, payments, subscriptions, and more.

(Optional) Seed the database

This template does not include a seed script by default. If you add one later, you can run it with:

pnpm prisma db seed

Start the development server

Now you're ready to start the development server:

pnpm dev

The application will be available at http://localhost:3000.

Verify the installation

To make sure everything is working correctly:

1. Visit the homepage - You should see the landing page
2. Check dark mode - Toggle the theme switcher in the header
3. Try login - Request an OTP at /auth/login (new emails create an account)
4. Check the database - Verify the user was created in your database

Next steps

Now that your installation is complete:

Troubleshooting

Port 3000 is already in use

If port 3000 is already in use, you can change it:

PORT=3001 pnpm dev

Database connection errors

Make sure your DATABASE_URL is correct and PostgreSQL is running:

# Check if PostgreSQL is running
pg_isready

# Or with psql
psql -h localhost -U your_username -d your_database

Prisma errors

If you're having Prisma-related issues, try:

# Generate Prisma client
pnpm prisma generate

# Reset the database (⚠️ deletes all data)
pnpm prisma migrate reset

Module not found errors

If you see module import errors after installation:

# Clear Nuxt cache
rm -rf .nuxt

# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install