We use tracking cookies to understand how you use the product and help us improve it. For more information on how we store cookies, read our  privacy policy.

Build & Deploy

Local builds, production deployment, and Vercel configuration

Plainform is optimized for deployment on Vercel with Next.js 16 features including Cache Components mode and Partial Prerendering.

Local Build

Test production builds locally before deploying:

Build and start (npm)
npm run build
npm run start
Build and start (pnpm)
pnpm build
pnpm start
Build and start (yarn)
yarn build
yarn start

Build process:

  1. Validates environment variables (via env.ts)
  2. Compiles TypeScript
  3. Generates Prisma client
  4. Processes MDX content (Fumadocs)
  5. Optimizes images and assets
  6. Creates production bundles with Turbopack
  7. Generates sitemap (postbuild script)

Build time: 30-90 seconds depending on content size and machine specs.

Build Output

Build output example
Route (app)                              Size     First Load JS
┌ ○ /                                    5.2 kB         120 kB
├ ○ /blog                                2.1 kB         115 kB
├ ◐ /docs                                1.8 kB         112 kB
├ ● /docs/[...slug]                      3.4 kB         118 kB
└ ○ /sign-in                             4.2 kB         119 kB

○  (Static)   Prerendered at build time
●  (SSG)      Prerendered with getStaticProps
◐  (Partial)  Partial Prerendering (static shell + dynamic streaming)

Route indicators:

  • ○ Static - Fully prerendered at build time
  • ● SSG - Static with data fetching
  • ◐ Partial - Static shell with dynamic content (Next.js 16)

Most routes use Partial Prerendering (◐) for optimal performance - static shell renders instantly while dynamic content streams.

Environment Variables

Required Variables

All environment variables are validated using Zod schemas in env.ts:

CategoryVariablesRequired
SiteSITE_URL, NEXT_PUBLIC_SITE_URL✅
ClerkCLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_*✅
StripeSTRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET✅
DatabaseDATABASE_URL, DIRECT_URL✅
AWS S3AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_*✅
ResendRESEND_API_KEY✅
MailchimpMAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID✅
PostHogNEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST✅

See Environment Variables for detailed configuration guide.

Local vs Production

Local development (.env):

  • Use test API keys (Stripe test mode, Clerk development)
  • Local database connection
  • http://localhost:3000 URLs

Production (Vercel):

  • Live API keys
  • Production database (Supabase)
  • Custom domain URLs
  • Webhook secrets for live mode

Deploy to Vercel

Connect Repository

  1. Go to vercel.com
  2. Click "Add New Project"
  3. Import your Git repository (GitHub/GitLab/Bitbucket)
  4. Select the repository

Configure Project

Framework Preset: Next.js (auto-detected)

Build Settings:

  • Build Command: npm run build (default)
  • Output Directory: .next (default)
  • Install Command: npm install (default)

Root Directory: Leave as . (project root)

Vercel automatically detects Next.js 16 and uses Turbopack for builds.

Add Environment Variables

Add all required environment variables in Vercel dashboard:

  1. Go to Project Settings → Environment Variables
  2. Add each variable from your .env file
  3. Select environments: Production, Preview, Development
  4. Click "Save"

Critical variables:

.env (Production)
# Site
SITE_URL=https://yourdomain.com
NEXT_PUBLIC_SITE_URL=https://yourdomain.com

# Clerk (production keys)
CLERK_SECRET_KEY=sk_live_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# Stripe (live keys)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Database (Supabase production)
DATABASE_URL=postgresql://...
DIRECT_URL=postgresql://...

# AWS S3
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=your-bucket
AWS_S3_REGION=us-east-1
AWS_S3_ENDPOINT=https://s3.amazonaws.com

# Email
RESEND_API_KEY=re_...

# Mailchimp
MAILCHIMP_API_KEY=...
MAILCHIMP_API_SERVER=us1
MAILCHIMP_AUDIENCE_ID=...

# Analytics
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

Deploy

Click "Deploy" and wait for build to complete (2-3 minutes).

Deployment process:

  1. Clones repository
  2. Installs dependencies
  3. Runs postinstall script (Prisma generate + Fumadocs)
  4. Builds application
  5. Runs postbuild script (sitemap generation)
  6. Deploys to Vercel Edge Network

Verify Deployment

  1. Check deployment URL (e.g., your-project.vercel.app)
  2. Test authentication (Clerk)
  3. Test payment flow (Stripe)
  4. Verify database connection
  5. Check email sending (Resend)

Custom Domain

Follow Vercel's domain setup guide to add a custom domain. After adding your domain, update these integration endpoints:

  • Clerk: Add production domain in Clerk Dashboard → Domains
  • Stripe: Update webhook endpoint to https://yourdomain.com/api/stripe/webhook
  • Environment Variables: Update SITE_URL and NEXT_PUBLIC_SITE_URL in Vercel

Database Migrations

Production Migration Strategy

Test Locally

Create migration
# Create migration
npx prisma migrate dev --name add_new_feature

# Test migration
npm run build
npm run start

Push to Repository

Push migration to repository
git add prisma/migrations
git commit -m "feat(db): add new feature migration"
git push origin main

Deploy Migration

Vercel automatically runs postinstall which includes prisma generate.

For applying migrations in production:

Deploy migration
# Option 1: Run manually via Vercel CLI
vercel env pull .env.production
npx prisma migrate deploy

# Option 2: Add to build command (not recommended for large migrations)
# Modify package.json:
"build": "prisma migrate deploy && next build"

Production migration best practices:

  • Always test migrations locally first
  • Backup database before major migrations
  • Use prisma migrate deploy (not migrate dev) in production
  • Consider downtime for breaking schema changes

Monitoring & Logs

Vercel Dashboard

Deployment logs:

  • Build output
  • Runtime errors
  • Function invocations
  • Edge network metrics

Real-time logs:

  1. Go to Project → Deployments
  2. Click on deployment
  3. View "Functions" tab for runtime logs

Error Tracking

Built-in error reporting:

  • Automatic error capture in production
  • Stack traces in Vercel dashboard
  • Function execution logs

PostHog integration:

Error tracking with PostHog
// Automatic error tracking
posthog.capture('$exception', {
  error: error.message,
  stack: error.stack,
});

Troubleshooting

Deployment Checklist

Before deploying to production:

  • All environment variables configured in Vercel
  • Database migrations tested locally
  • Stripe webhooks configured with production endpoint
  • Clerk production instance configured
  • Custom domain DNS configured
  • SSL certificate provisioned (automatic)
  • S3 bucket CORS configured
  • Email sending tested (Resend)
  • Analytics tracking verified (PostHog)
  • Error monitoring enabled
  • Build succeeds locally: npm run build
  • Production build tested: npm run start
  • All integrations tested on staging/preview deployment

Preview Deployments

Vercel automatically creates preview deployments for:

  • Pull requests
  • Branch pushes
  • Manual deployments

Preview features:

  • Unique URL per deployment
  • Same environment variables as production (or custom)
  • Full functionality testing before merge
  • Automatic comments on PRs with preview URL

Test on preview:

Test preview deployment
# Get preview URL from Vercel dashboard or PR comment
https://your-project-git-feature-branch.vercel.app

Next Steps

How is this guide ?

Last updated on

Git Workflow

Branching strategy, commit conventions, and automated hooks

Troubleshooting

Common issues, error messages, and solutions for development and production

On this page

Local Build
Build Output
Environment Variables
Required Variables
Local vs Production
Deploy to Vercel
Connect Repository
Configure Project
Add Environment Variables
Deploy
Verify Deployment
Custom Domain
Database Migrations
Production Migration Strategy
Test Locally
Push to Repository
Deploy Migration
Monitoring & Logs
Vercel Dashboard
Error Tracking
Troubleshooting
Deployment Checklist
Preview Deployments
Next Steps