Skip to main content

​
Quick Start

Get Shipr running locally in under 10 minutes. This guide will walk you through cloning the repo, installing dependencies, and running your first local development server.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ installed on your machine
  • pnpm package manager (npm install -g pnpm)
  • A GitHub account (for cloning)
  • Basic accounts for Clerk and Convex (free tiers available)
You can create free accounts for Clerk and Convex during this setup process.

​
Installation

1

Clone the repository

Clone Shipr to your local machine:
git clone <repo-url>
cd shipr
2

Install dependencies

Install all required packages using pnpm:
pnpm install
This will install Next.js, Clerk, Convex, and all other dependencies listed in package.json.
3

Set up environment variables

Copy the example environment file:
cp .env.example .env
For now, you’ll need at minimum:
  • Clerk authentication keys
  • Convex deployment URL
  • Site URL (can be http://localhost:3000 for local dev)
We’ll configure these in the next steps.

​
Configure Clerk

1

Create a Clerk application

  1. Go to clerk.com and create a free account
  2. Create a new application
  3. Choose your preferred authentication methods (email, Google, GitHub, etc.)
2

Copy your API keys

From your Clerk dashboard, copy these values to your .env file:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
3

Configure JWT issuer

In your Clerk dashboard, find your JWT issuer domain and add it to .env:
CLERK_JWT_ISSUER_DOMAIN=https://...clerk.accounts.dev
This is required for Convex authentication.

​
Configure Convex

1

Create a Convex project

  1. Visit convex.dev and sign up
  2. Create a new project
  3. The Convex CLI will guide you through the setup
2

Initialize Convex in your project

Run the Convex development server:
npx convex dev
This will:
  • Push your database schema to Convex
  • Generate your deployment URL
  • Start watching for schema changes
Keep this terminal window open - Convex needs to run alongside Next.js during development.
3

Copy your Convex URL

After running npx convex dev, copy the deployment URL to your .env file:
NEXT_PUBLIC_CONVEX_URL=https://...convex.cloud
4

Configure Clerk authentication in Convex

In the Convex dashboard:
  1. Navigate to your project settings
  2. Go to Authentication settings
  3. Add your CLERK_JWT_ISSUER_DOMAIN value

​
Set Site URL

For local development, set your site URL in .env: 
NEXT_PUBLIC_SITE_URL=http://localhost:3000
The site URL is used for metadata, canonical URLs, and OG images. You’ll change this to your production URL when deploying.

​
Start the Development Server

Now you’re ready to run Shipr locally!
1

Make sure Convex is running

In one terminal window, ensure Convex dev server is running:
npx convex dev
2

Start Next.js

In a second terminal window, start the Next.js development server:
pnpm dev
3

Open your browser

Navigate to http://localhost:3000You should see the Shipr landing page!

​
Test Authentication

1

Sign up

Click the “Sign Up” button in the header and create a test account using any of your configured authentication methods.
2

Complete onboarding

After signing up, you’ll be redirected to the onboarding flow. This multi-step process welcomes new users and captures their information.You can skip onboarding if you want to explore the dashboard directly.
3

Explore the dashboard

Once authenticated, you’ll see the dashboard with:
  • User profile information from Clerk
  • Navigation to AI chat, file upload, and other features
  • Your current billing plan (Free by default)

​
What’s Working

At this point, you have: ✅ Next.js 16 running with App Router
✅ Clerk authentication with sign-up/sign-in flows
✅ Convex database with real-time sync
✅ User sync between Clerk and Convex
✅ Protected dashboard routes
✅ Onboarding flow for new users
✅ Dark/light theme switching

​
Optional: Add More Services

To enable additional features, you’ll need to configure:
These services are optional for local development but recommended for production deployments.

​
Available Scripts

Here are the key commands you’ll use: 
pnpm dev        # Start Next.js dev server
pnpm build      # Build for production
pnpm start      # Start production server
pnpm lint       # Run ESLint
npx convex dev  # Start Convex dev mode

​
Next Steps

Complete Installation

Set up all optional services for full functionality

Architecture

Understand how Shipr is structured

Authentication

Deep dive into Clerk and user management

Deployment

Deploy your SaaS to production

​
Troubleshooting

​
Convex authentication errors

If you see authentication errors, verify that:
  • CLERK_JWT_ISSUER_DOMAIN is set correctly in both .env and Convex dashboard
  • You’ve restarted both npx convex dev and pnpm dev after changing environment variables

​
User not syncing to Convex

If your Clerk user doesn’t appear in Convex:
  • Check the browser console for errors
  • Verify your Convex deployment URL is correct
  • Make sure you’re signed in and visiting a dashboard page (user sync happens on protected routes)

​
Port already in use

If port 3000 is already in use: 
pnpm dev -- -p 3001
Then update NEXT_PUBLIC_SITE_URL to match the new port.

Build docs developers (and LLMs) love

Get started for freeTalk to us