MyApp

Get Plainform running on your local machine in under 30 minutes. This guide walks you through cloning the repository, installing dependencies, configuring environment variables, and running your first build.

What You'll Need

Before starting, make sure you have Node.js 18+ installed and accounts created for Clerk, Stripe, Supabase, AWS, Resend, Mailchimp, and PostHog. Don't worry—we'll guide you through the setup for each service.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ - Download here
npm, pnpm, or yarn - Package manager (npm comes with Node.js)
Git - Download here
Code Editor - Cursor (recommended) or VS Code

You'll also need accounts for these services (free tiers available):

Clerk - Authentication
Stripe - Payments
Supabase - Database hosting
AWS - S3 storage
Resend - Transactional emails
Mailchimp - Newsletter management
PostHog - Analytics

GitHub Access

After purchasing Plainform, you'll be added as a collaborator to the private repository using the GitHub username you provided during checkout. Check your email for the invitation.

Step 1: Clone the Repository

After accepting the GitHub invitation, choose one of three methods to get the code:

Option A: Direct Clone (Recommended)

Clone the repository directly to your local machine:

Clone repository (npm)

git clone https://github.com/GeluHorotan/plainform-essentials.git your-project-name
cd your-project-name

Clone repository (pnpm)

git clone https://github.com/GeluHorotan/plainform-essentials.git your-project-name
cd your-project-name

Clone repository (yarn)

git clone https://github.com/GeluHorotan/plainform-essentials.git your-project-name
cd your-project-name

This method is best for getting started quickly.

Option B: Fork the Repository

Fork the repository to your own GitHub account for easier customization and version control:

Go to github.com/GeluHorotan/plainform-essentials
Click the Fork button in the top right
Clone your forked repository:

Clone forked repository

git clone https://github.com/your-username/plainform-essentials.git your-project-name
cd your-project-name

This method is ideal if you want to maintain your own version and easily pull updates.

Option C: Use as Template

Create a new repository based on Plainform:

Go to github.com/GeluHorotan/plainform-essentials
Click Use this template → Create a new repository
Name your repository and click Create repository
Clone your new repository:

Clone template repository

git clone https://github.com/your-username/your-new-repo.git
cd your-new-repo

This method creates a clean repository without the Plainform commit history.

Step 2: Install Dependencies

Install all required packages using your preferred package manager:

Install dependencies (npm)

npm install

Install dependencies (pnpm)

pnpm install

Install dependencies (yarn)

yarn install

This will install all dependencies and automatically run:

prisma generate - Generates the Prisma client
fumadocs-mdx - Processes MDX content

Installation Time

The first installation may take 2-5 minutes depending on your internet connection. Subsequent installs will be faster thanks to package caching.

Step 3: Set Up Environment Variables

Create a .env file in the root directory and configure all required environment variables.

Copy the example environment file:

Copy environment file

cp .env.example .env

Here's how your complete .env file should look:

.env

# Site Configuration
SITE_URL="http://localhost:3000"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"

# Clerk Authentication
NEXT_PUBLIC_CLERK_SIGN_IN_URL='/sign-in'
NEXT_PUBLIC_CLERK_SIGN_UP_URL='/sign-up'
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="your_clerk_publishable_key"
CLERK_SECRET_KEY="your_clerk_secret_key"

# Stripe Payments
STRIPE_SECRET_KEY="your_stripe_secret_key"
STRIPE_PUBLISHABLE_KEY="your_stripe_publishable_key"
STRIPE_WEBHOOK_SECRET="your_stripe_webhook_secret"

# Database (Supabase PostgreSQL)
DATABASE_URL="your_supabase_connection_string"
DIRECT_URL="your_supabase_direct_connection_string"

# AWS S3 Storage
AWS_ACCESS_KEY_ID="your_aws_access_key"
AWS_SECRET_ACCESS_KEY="your_aws_secret_key"
AWS_S3_ENDPOINT="https://your-bucket.s3.region.amazonaws.com"
AWS_S3_REGION="your_aws_region"
AWS_S3_BUCKET="your_bucket_name"

# Resend Email
RESEND_API_KEY="your_resend_api_key"

# Mailchimp Newsletter
MAILCHIMP_API_KEY="your_mailchimp_api_key"
MAILCHIMP_API_SERVER="us19"
MAILCHIMP_AUDIENCE_ID="your_audience_id"

# PostHog Analytics
NEXT_PUBLIC_POSTHOG_KEY="your_posthog_key"
NEXT_PUBLIC_POSTHOG_HOST="https://eu.i.posthog.com"

Need Help with Environment Variables?

For detailed explanations of each variable, including types, requirements, and setup instructions, see the Environment Variables Guide.

Get Your API Keys

You'll need to create accounts and get API keys from each service:

Clerk Setup

Get your Clerk API keys for authentication

Stripe Setup

Configure Stripe for payment processing

Supabase Setup

Set up PostgreSQL database on Supabase

AWS S3 Setup

Configure S3 bucket for file storage

Resend Setup

Get Resend API key for transactional emails

Environment Variables

Complete guide for all environment variables

Step 5: Run the Development Server

Start the Next.js development server with Turbopack:

Start dev server (npm)

npm run dev

Start dev server (pnpm)

pnpm dev

Start dev server (yarn)

yarn dev

Open http://localhost:3000 in your browser to see your application running.

Success!

If you see the Plainform homepage, congratulations! Your local environment is set up correctly.

Step 6: Verify Installation

Check that everything is working correctly:

Test Authentication

Navigate to http://localhost:3000/sign-up
Create a test account
Verify you can sign in and out

Test Stripe Webhooks (Optional)

To test payment webhooks locally, run the Stripe CLI in a separate terminal:

Stripe webhook listener (npm)

npm run stripe:listen

Stripe webhook listener (pnpm)

pnpm stripe:listen

Stripe webhook listener (yarn)

yarn stripe:listen

Stripe CLI Required

You need to install the Stripe CLI and authenticate with stripe login before running webhook listeners. Learn more in the Stripe setup guide.

Check the Documentation

Navigate to http://localhost:3000/docs to view the documentation site powered by Fumadocs.

Common Issues

Port Already in Use

If port 3000 is already in use, you can specify a different port:

Use different port

PORT=3001 npm run dev

Environment Variable Errors

If you see validation errors on startup, check that:

All required variables are present in .env
No variables have trailing spaces
String values are properly quoted if they contain special characters
The .env file is in the root directory (not in a subdirectory)

Module Not Found Errors

If you see "Module not found" errors:

Delete node_modules and lock files:
Delete node_modules
```
rm -rf node_modules package-lock.json
```
Reinstall dependencies:
Reinstall dependencies
```
npm install
```

Need More Help?

Check the troubleshooting guide for more solutions.

Next Steps

Now that Plainform is installed, here's what to do next:

Project Structure

Understand the folder organization and file conventions

Environment Variables

Learn about all configuration options

Authentication Setup

Configure Clerk authentication in detail

Deploy to Vercel

Launch your app to production

What You'll Need

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ - Download here
npm, pnpm, or yarn - Package manager (npm comes with Node.js)
Git - Download here
Code Editor - Cursor (recommended) or VS Code

You'll also need accounts for these services (free tiers available):

Clerk - Authentication
Stripe - Payments
Supabase - Database hosting
AWS - S3 storage
Resend - Transactional emails
Mailchimp - Newsletter management
PostHog - Analytics

GitHub Access

After purchasing Plainform, you'll be added as a collaborator to the private repository using the GitHub username you provided during checkout. Check your email for the invitation.

Step 1: Clone the Repository

After accepting the GitHub invitation, choose one of three methods to get the code:

Option A: Direct Clone (Recommended)

Clone the repository directly to your local machine:

Clone repository (npm)

git clone https://github.com/GeluHorotan/plainform-essentials.git your-project-name
cd your-project-name

Clone repository (pnpm)

git clone https://github.com/GeluHorotan/plainform-essentials.git your-project-name
cd your-project-name

Clone repository (yarn)

git clone https://github.com/GeluHorotan/plainform-essentials.git your-project-name
cd your-project-name

This method is best for getting started quickly.

Option B: Fork the Repository

Fork the repository to your own GitHub account for easier customization and version control:

Go to github.com/GeluHorotan/plainform-essentials
Click the Fork button in the top right
Clone your forked repository:

Clone forked repository

git clone https://github.com/your-username/plainform-essentials.git your-project-name
cd your-project-name

This method is ideal if you want to maintain your own version and easily pull updates.

Option C: Use as Template

Create a new repository based on Plainform:

Go to github.com/GeluHorotan/plainform-essentials
Click Use this template → Create a new repository
Name your repository and click Create repository
Clone your new repository:

Clone template repository

git clone https://github.com/your-username/your-new-repo.git
cd your-new-repo

This method creates a clean repository without the Plainform commit history.

Step 2: Install Dependencies

Install all required packages using your preferred package manager:

Install dependencies (npm)

npm install

Install dependencies (pnpm)

pnpm install

Install dependencies (yarn)

yarn install

This will install all dependencies and automatically run:

prisma generate - Generates the Prisma client
fumadocs-mdx - Processes MDX content

Installation Time

The first installation may take 2-5 minutes depending on your internet connection. Subsequent installs will be faster thanks to package caching.

Step 3: Set Up Environment Variables

Create a .env file in the root directory and configure all required environment variables.

Copy the example environment file:

Copy environment file

cp .env.example .env

Here's how your complete .env file should look:

.env

# Site Configuration
SITE_URL="http://localhost:3000"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"

# Clerk Authentication
NEXT_PUBLIC_CLERK_SIGN_IN_URL='/sign-in'
NEXT_PUBLIC_CLERK_SIGN_UP_URL='/sign-up'
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="your_clerk_publishable_key"
CLERK_SECRET_KEY="your_clerk_secret_key"

# Stripe Payments
STRIPE_SECRET_KEY="your_stripe_secret_key"
STRIPE_PUBLISHABLE_KEY="your_stripe_publishable_key"
STRIPE_WEBHOOK_SECRET="your_stripe_webhook_secret"

# Database (Supabase PostgreSQL)
DATABASE_URL="your_supabase_connection_string"
DIRECT_URL="your_supabase_direct_connection_string"

# AWS S3 Storage
AWS_ACCESS_KEY_ID="your_aws_access_key"
AWS_SECRET_ACCESS_KEY="your_aws_secret_key"
AWS_S3_ENDPOINT="https://your-bucket.s3.region.amazonaws.com"
AWS_S3_REGION="your_aws_region"
AWS_S3_BUCKET="your_bucket_name"

# Resend Email
RESEND_API_KEY="your_resend_api_key"

# Mailchimp Newsletter
MAILCHIMP_API_KEY="your_mailchimp_api_key"
MAILCHIMP_API_SERVER="us19"
MAILCHIMP_AUDIENCE_ID="your_audience_id"

# PostHog Analytics
NEXT_PUBLIC_POSTHOG_KEY="your_posthog_key"
NEXT_PUBLIC_POSTHOG_HOST="https://eu.i.posthog.com"

Need Help with Environment Variables?

For detailed explanations of each variable, including types, requirements, and setup instructions, see the Environment Variables Guide.

npm run dev

Start dev server (pnpm)

pnpm dev

Start dev server (yarn)

yarn dev

Open http://localhost:3000 in your browser to see your application running.

Success!

If you see the Plainform homepage, congratulations! Your local environment is set up correctly.

Step 6: Verify Installation

Check that everything is working correctly:

Test Authentication

Navigate to http://localhost:3000/sign-up
Create a test account
Verify you can sign in and out

Test Stripe Webhooks (Optional)

To test payment webhooks locally, run the Stripe CLI in a separate terminal:

Stripe webhook listener (npm)

npm run stripe:listen

Stripe webhook listener (pnpm)

pnpm stripe:listen

Stripe webhook listener (yarn)

yarn stripe:listen

Stripe CLI Required

You need to install the Stripe CLI and authenticate with stripe login before running webhook listeners. Learn more in the Stripe setup guide.

PORT=3001 npm run dev

Environment Variable Errors

If you see validation errors on startup, check that:

All required variables are present in .env
No variables have trailing spaces
String values are properly quoted if they contain special characters
The .env file is in the root directory (not in a subdirectory)

Module Not Found Errors

If you see "Module not found" errors:

Delete node_modules and lock files:
Delete node_modules
```
rm -rf node_modules package-lock.json
```
Reinstall dependencies:
Reinstall dependencies
```
npm install
```

Need More Help?

Check the troubleshooting guide for more solutions.

Installation

Clerk Setup

Stripe Setup

Supabase Setup

AWS S3 Setup

Resend Setup

Environment Variables

Project Structure

Environment Variables

Authentication Setup

Deploy to Vercel

On this page

Installation

Clerk Setup

Stripe Setup

Supabase Setup

AWS S3 Setup

Resend Setup

Environment Variables

Project Structure

Environment Variables

Authentication Setup

Deploy to Vercel

On this page