Skip to main content

​
Overview

Shipr is optimized for deployment on Vercel with Convex as the backend. This guide covers deploying your Next.js application, setting up Convex, and configuring all required services.

​
Vercel Deployment

1

Push to GitHub

Push your repository to GitHub:
git add .
git commit -m "Initial commit"
git push origin main
2

Import to Vercel

  1. Go to vercel.com/new
  2. Import your GitHub repository
  3. Vercel will auto-detect Next.js configuration
3

Configure Environment Variables

Add all required environment variables in the Vercel dashboard under Settings → Environment Variables.See the Environment Variables page for a complete reference.Required variables:
  • NEXT_PUBLIC_SITE_URL
  • NEXT_PUBLIC_CONVEX_URL
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  • CLERK_SECRET_KEY
  • CLERK_JWT_ISSUER_DOMAIN
  • AI_GATEWAY_API_KEY
  • RESEND_API_KEY
4

Deploy

Click Deploy. Vercel will automatically build and deploy your application.

​
Build Settings

Vercel should auto-detect these settings, but verify:
  • Framework: Next.js
  • Build Command: pnpm build
  • Output Directory: .next
  • Install Command: pnpm install

​
Convex Deployment

Convex serves as your backend database and real-time sync layer.
1

Install Convex CLI

Install the Convex CLI globally:
pnpm add -g convex
2

Sync Schema Locally

Run Convex in development mode to sync your schema:
npx convex dev
This creates your development Convex deployment and syncs your schema from the convex/ directory.
3

Deploy to Production

Deploy your Convex functions to production:
npx convex deploy
This creates a production deployment and provides your NEXT_PUBLIC_CONVEX_URL.
4

Configure Clerk Authentication

  1. Go to the Convex Dashboard
  2. Navigate to your production deployment
  3. Go to Settings → Authentication
  4. Add CLERK_JWT_ISSUER_DOMAIN from your Clerk dashboard
This enables Convex to verify Clerk JWT tokens for authenticated queries and mutations.

​
Service Configuration

​
Clerk

1

Create Clerk Application

  1. Sign up at clerk.com
  2. Create a new application
  3. Choose your authentication methods (email, social, etc.)
2

Copy API Keys

Copy these values to your environment variables:
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  • CLERK_SECRET_KEY
  • CLERK_JWT_ISSUER_DOMAIN
3

Configure Billing (Optional)

Enable Clerk Billing if you want to use Pro/Free plan gating features in your SaaS.

​
Resend

1

Create Resend Account

Sign up at resend.com
2

Add Verified Domain

Add and verify your sending domain, or use the sandbox sender for testing.
3

Configure API Key

  1. Generate an API key in the Resend dashboard
  2. Add RESEND_API_KEY to your environment variables
  3. Set RESEND_FROM_EMAIL to your verified sender address (e.g., [email protected])
The default is [email protected] which only works in sandbox mode.
The email system is configured in src/lib/emails/send.ts and available via POST /api/email.

​
Sentry (Optional)

1

Create Sentry Project

  1. Sign up at sentry.io
  2. Create a new Next.js project
2

Configure Environment Variables

Add these to your environment:
  • SENTRY_AUTH_TOKEN - for uploading source maps
  • NEXT_PUBLIC_SENTRY_DSN - for error reporting
Source maps are automatically uploaded during build via @sentry/nextjs. Error tracking helpers are available in src/lib/sentry.ts.

​
PostHog (Optional)

1

Create PostHog Project

Sign up at posthog.com and create a project.
2

Add Environment Variables

  • NEXT_PUBLIC_POSTHOG_KEY - your project API key
  • NEXT_PUBLIC_POSTHOG_HOST - ingest host (e.g., https://us.i.posthog.com)
Shipr uses a reverse proxy via Next.js rewrites (configured in next.config.ts) to bypass ad blockers.

​
Production Considerations

​
Environment Variables

Ensure all production URLs are correctly set:
  • NEXT_PUBLIC_SITE_URL should match your production domain
  • NEXT_PUBLIC_CONVEX_URL should point to your production Convex deployment
  • All secret keys should be different from development

​
Rate Limiting

Configure rate limits for production usage:
  • AI_CHAT_RATE_LIMIT_MAX_REQUESTS - chat requests per window
  • AI_CHAT_RATE_LIMIT_WINDOW_MS - rate limit window duration
  • FILE_IMAGE_UPLOAD_RATE_LIMIT_MAX_UPLOADS - image uploads per window

​
AI Chat Limits

Set appropriate limits for your SaaS:
  • AI_CHAT_ENFORCE_LIFETIME_MESSAGE_LIMIT - enable message caps
  • AI_CHAT_LIFETIME_MESSAGE_LIMIT - total messages per user
  • AI_CHAT_HISTORY_MAX_THREADS - max chat threads per user

​
Build Output

Vercel automatically builds your Next.js application. Monitor build logs for:
  • TypeScript errors
  • Missing environment variables
  • Build warnings
  • Bundle size issues

​
Domain Configuration

  1. Add your custom domain in Vercel dashboard
  2. Update DNS records as instructed
  3. Update NEXT_PUBLIC_SITE_URL to match your domain
  4. Redeploy to regenerate metadata and sitemaps

Build docs developers (and LLMs) love

Get started for freeTalk to us