Installation

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.

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

Step 1: Clone the Repository

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

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

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

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

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

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

Step 2: Install Dependencies

Install all required packages using your preferred package manager:

npm install

pnpm install

yarn install

This will install all dependencies and automatically run:

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

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:

cp .env.example .env

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

# 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"

Get Your API Keys

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

Step 5: Run the Development Server

Start the Next.js development server with Turbopack:

npm run dev

pnpm dev

yarn dev

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

Step 6: Verify Installation

Check that everything is working correctly:

Test Authentication

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

Test Stripe Webhooks (Optional)

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

npm run stripe:listen

pnpm stripe:listen

yarn stripe:listen

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:

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:

1. Delete node_modules and lock files:

   rm -rf node_modules package-lock.json

2. Reinstall dependencies:

   npm install

Next Steps

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