Installation

This guide covers the complete setup of Shipr, including all required services and optional integrations. For a faster start, see the Quick Start guide.

Prerequisites

Node.js 18+

Download and install from nodejs.orgVerify installation:

node --version

pnpm package manager

Install pnpm globally:

npm install -g pnpm

Verify installation:

pnpm --version

Git

Ensure Git is installed for cloning the repository:

git --version

Initial Setup

Clone the repository

git clone <repo-url>
cd shipr

Install dependencies

pnpm install

This installs all packages from package.json including:

next (16.1.6) - Framework
@clerk/nextjs - Authentication
convex - Database and backend
@ai-sdk/react and ai - AI functionality
resend - Email sending
@sentry/nextjs - Error tracking
posthog-js - Analytics
UI libraries (shadcn, Tailwind, etc.)

Create environment file

cp .env.example .env

Configure Clerk (Required)

Clerk handles authentication, user management, and billing plan detection.

Create a Clerk account

Visit clerk.com
Sign up for a free account
Create a new application

Configure authentication methods

In your Clerk dashboard:

Enable email/password authentication
Optionally enable social providers (Google, GitHub, etc.)
Configure your application name and branding

Copy API keys

From your Clerk dashboard, add these to .env:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

Set JWT issuer domain

Find your JWT issuer domain in Clerk dashboard under “API Keys”:

CLERK_JWT_ISSUER_DOMAIN=https://...clerk.accounts.dev

This must match exactly what Clerk provides, including the https:// protocol.

Configure redirect URLs

These are already set in .env.example:

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

You can customize these URLs if needed, but the defaults work out of the box.

(Optional) Enable Clerk Billing

If you want to use plan gating (Free/Pro):

Enable Clerk Billing in your dashboard
Configure your plans
The useUserPlan hook will automatically detect the user’s plan

Configure Convex (Required)

Convex is your realtime database and backend.

Create a Convex account

Go to convex.dev
Sign up with GitHub (recommended) or email
Create a new project

Initialize Convex

Run the Convex development server:

npx convex dev

This will:

Prompt you to log in if needed
Push your schema from convex/schema.ts
Generate your deployment URL
Start watching for changes

Keep this terminal window open during development. Convex runs alongside Next.js.

Copy deployment URL

After running npx convex dev, copy the URL to .env:

NEXT_PUBLIC_CONVEX_URL=https://...convex.cloud

Configure Clerk authentication

In the Convex dashboard:

Select your project
Go to Settings → Authentication
Add Clerk as an authentication provider
Enter your CLERK_JWT_ISSUER_DOMAIN value

This allows Convex to verify Clerk JWTs.

Set Site URL (Required)

The site URL is used for metadata, canonical URLs, sitemaps, and OG images.

# For local development
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# For production (update before deploying)
NEXT_PUBLIC_SITE_URL=https://yourdomain.com

Configure Resend (Required for Email)

Resend handles transactional emails like welcome messages and plan change notifications.

Create a Resend account

Visit resend.com
Sign up for a free account
You get 100 emails/day on the free tier

Get your API key

From the Resend dashboard:

Navigate to API Keys
Create a new API key
Copy it to .env:

RESEND_API_KEY=re_...

Configure sender email

For local development/testing:

RESEND_FROM_EMAIL=[email protected]

For production with a verified domain:

RESEND_FROM_EMAIL=[email protected]

Resend’s sandbox sender works for testing, but you’ll need to verify your domain for production.

(Optional) Verify your domain

For production:

In Resend dashboard, go to Domains
Add your domain
Add the DNS records Resend provides
Wait for verification (usually a few minutes)

Configure AI Chat (Optional)

The AI chat feature requires Vercel AI Gateway.

Get AI Gateway API key

Visit vercel.com
Create or select a project
Navigate to AI Gateway settings
Generate an API key

Add to .env:

AI_GATEWAY_API_KEY=vck_...

Configure AI settings

Customize the AI chat behavior:

# Model to use (default: openai/gpt-4.1-mini)
AI_CHAT_MODEL=openai/gpt-4.1-mini

# System prompt
AI_CHAT_SYSTEM_PROMPT=You are Shipr's AI assistant helping builders ship SaaS faster.

# Enabled tools (comma-separated)
AI_CHAT_TOOLS=getCurrentDateTime,calculate

# Max model steps per response
AI_CHAT_MAX_STEPS=5

# Rate limiting
AI_CHAT_RATE_LIMIT_MAX_REQUESTS=20
AI_CHAT_RATE_LIMIT_WINDOW_MS=60000

Configure chat history

Chat history is stored in Convex:

# Enable/disable chat history
AI_CHAT_HISTORY_ENABLED=true

# Max characters per message
AI_CHAT_HISTORY_MAX_MESSAGE_LENGTH=8000

# Max messages per thread
AI_CHAT_HISTORY_MAX_MESSAGES_PER_THREAD=120

# Max threads per user
AI_CHAT_HISTORY_MAX_THREADS=50

# Max title length
AI_CHAT_HISTORY_THREAD_TITLE_MAX_LENGTH=80

# Query limit
AI_CHAT_HISTORY_QUERY_LIMIT=200

Configure lifetime message limits

Prevent abuse with per-user message caps:

# Enable lifetime cap (default: true for boilerplate protection)
AI_CHAT_ENFORCE_LIFETIME_MESSAGE_LIMIT=true

# Max messages per user account (default: 1)
AI_CHAT_LIFETIME_MESSAGE_LIMIT=1

Set AI_CHAT_ENFORCE_LIFETIME_MESSAGE_LIMIT=false to disable this limit for your production app.

Configure PostHog (Optional)

PostHog provides product analytics with a reverse proxy to bypass ad blockers.

Create a PostHog project

Visit posthog.com
Sign up for a free account
Create a new project

Copy your credentials

From your PostHog project settings:

NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Shipr is configured to reverse-proxy PostHog requests through Next.js rewrites (see next.config.ts), which helps bypass ad blockers.

Configure Sentry (Optional)

Sentry provides error tracking and performance monitoring.

Create a Sentry project

Go to sentry.io
Create an account and organization
Create a new Next.js project

Add Sentry credentials

# Auth token for uploading source maps
SENTRY_AUTH_TOKEN=sntrys_...

# Your Sentry DSN
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/...

Source maps

Source maps are automatically uploaded during pnpm build via the @sentry/nextjs plugin.

Source maps help you debug production errors with readable stack traces.

Configure File Upload Rate Limiting (Optional)

Control image upload limits per user:

# Max uploads per user in the time window
FILE_IMAGE_UPLOAD_RATE_LIMIT_MAX_UPLOADS=10

# Time window in milliseconds (60000 = 1 minute)
FILE_IMAGE_UPLOAD_RATE_LIMIT_WINDOW_MS=60000

Set either value to 0 to disable rate limiting for image uploads.

Complete .env Example

Here’s what your .env should look like with all required services configured:

# Site
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CLERK_JWT_ISSUER_DOMAIN=https://...clerk.accounts.dev
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# Convex Database
NEXT_PUBLIC_CONVEX_URL=https://...convex.cloud

# Resend Email
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=[email protected]

# Vercel AI Gateway (optional)
AI_GATEWAY_API_KEY=vck_...

# PostHog Analytics (optional)
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

# Sentry Error Tracking (optional)
SENTRY_AUTH_TOKEN=sntrys_...
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/...

Start Development

With all services configured, you’re ready to run Shipr:

Start Convex

In one terminal:

npx convex dev

Start Next.js

In another terminal:

pnpm dev

Open your browser

Visit http://localhost:3000

Verify Setup

Check authentication

Click “Sign Up” in the header
Create a test account
Complete the onboarding flow
Verify you can access the dashboard

Check Convex sync

Open the Convex dashboard
Navigate to your project’s data
Check the users table - you should see your test user

Check email (if configured)

Test the email endpoint:

# In the dashboard, navigate to a page that triggers a welcome email
# Or test via the API route directly

Check AI chat (if configured)

Navigate to /dashboard/chat
Send a test message
Verify you get a response from the AI

Database Schema

Shipr’s Convex schema (convex/schema.ts) includes:

Users Table

Field	Type	Description
`clerkId`	`string`	Clerk user ID (indexed)
`email`	`string`	Primary email address
`name`	`string?`	Full name
`imageUrl`	`string?`	Profile image URL
`plan`	`string?`	Billing plan: `"free"` or `"pro"`
`onboardingCompleted`	`boolean?`	Whether user finished onboarding
`onboardingStep`	`string?`	Current step: `"welcome"`, `"profile"`, etc.

Files Table

Field	Type	Description
`storageId`	`id("_storage")`	Convex storage reference
`userId`	`id("users")`	Owning user
`fileName`	`string`	Original filename (sanitized)
`mimeType`	`string`	MIME type (e.g., `"image/png"`)
`size`	`number`	File size in bytes

Chat Tables

chatThreads:

userId - Owner of the thread
title - Auto-generated thread title
lastMessageAt - Timestamp for sorting

chatMessages:

userId - Message owner
threadId - Parent thread
role - "user" or "assistant"
content - Message text

All tables automatically include _id and _creationTime fields from Convex.

Next Steps

Architecture

Learn how Shipr’s components work together

Authentication

Deep dive into Clerk and user sync

AI Chat

Configure and extend the AI chat feature

Deployment

Deploy to production on Vercel

Troubleshooting

Module not found errors

# Clear node_modules and reinstall
rm -rf node_modules
pnpm install

Convex schema errors

# Push schema again
npx convex dev --once

Environment variables not loading

Verify .env file exists in the root directory
Restart both npx convex dev and pnpm dev
Check for typos in variable names (they’re case-sensitive)

Clerk/Convex authentication mismatch

Verify CLERK_JWT_ISSUER_DOMAIN matches in:
- Your .env file
- Convex dashboard authentication settings
Ensure it includes https:// protocol
Restart all servers after changing

Port conflicts

# Use a different port
pnpm dev -- -p 3001

# Update your site URL
NEXT_PUBLIC_SITE_URL=http://localhost:3001

Get Started

Core Features

Integrations

Deployment

Installation

Installation

Prerequisites

Initial Setup

Configure Clerk (Required)

Configure Convex (Required)

Set Site URL (Required)

Configure Resend (Required for Email)

Configure AI Chat (Optional)

Configure PostHog (Optional)

Configure Sentry (Optional)

Configure File Upload Rate Limiting (Optional)

Complete .env Example

Start Development

Verify Setup

Database Schema

Users Table

Files Table

Chat Tables

Next Steps

Architecture

Authentication

AI Chat

Deployment

Troubleshooting

Module not found errors

Convex schema errors

Environment variables not loading

Clerk/Convex authentication mismatch

Port conflicts

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Deployment

​Installation

​Prerequisites

​Initial Setup

​Configure Clerk (Required)

​Configure Convex (Required)

​Set Site URL (Required)

​Configure Resend (Required for Email)

​Configure AI Chat (Optional)

​Configure PostHog (Optional)

​Configure Sentry (Optional)

​Configure File Upload Rate Limiting (Optional)

​Complete .env Example

​Start Development

​Verify Setup

​Database Schema

​Users Table

​Files Table

​Chat Tables

​Next Steps

Architecture

Authentication

AI Chat

Deployment

​Troubleshooting

​Module not found errors

​Convex schema errors

​Environment variables not loading

​Clerk/Convex authentication mismatch

​Port conflicts

Build docs developers (and LLMs) love

Installation

Prerequisites

Initial Setup

Configure Clerk (Required)

Configure Convex (Required)

Set Site URL (Required)

Configure Resend (Required for Email)

Configure AI Chat (Optional)

Configure PostHog (Optional)

Configure Sentry (Optional)

Configure File Upload Rate Limiting (Optional)

Complete .env Example

Start Development

Verify Setup

Database Schema

Users Table

Files Table

Chat Tables

Next Steps

Troubleshooting

Module not found errors

Convex schema errors

Environment variables not loading

Clerk/Convex authentication mismatch

Port conflicts