Quick Start Guide

Get the AI Starter Kit running on your machine in 5 minutes. This guide will walk you through the fastest path to a working application.

Prerequisites
Automated Setup (Recommended)
Manual Installation Steps
Verification
What's Next?
Troubleshooting Quick Setup

Prerequisites

Before you begin, make sure you have the following installed:

Required

✅ Node.js 18.x or later (Download here)

node --version  # Should be 18.x or higher

✅ pnpm (recommended) or npm

# Install pnpm globally if you don't have it
npm install -g pnpm

# Verify installation
pnpm --version

Optional but Helpful

Git for version control
VS Code or your preferred code editor
openssl for generating secrets (comes pre-installed on macOS/Linux)

Automated Setup (Recommended)

The easiest way to get started is with our automated setup script. It handles everything for you!

# Clone the repository
git clone https://github.com/robertguss/ai-starter-kit.git
cd ai-starter-kit

# Run the setup script
./setup.sh

What the setup script does:

✅ Checks prerequisites (Node.js 18+, pnpm)
✅ Installs pnpm automatically if missing
✅ Installs all dependencies
✅ Guides you through Convex authentication (browser login)
✅ Configures all environment variables automatically
✅ Starts the development servers

Windows Users: Run bash setup.sh in Git Bash or WSL.

After the script completes, your dev server will be running at http://localhost:3000!

Manual Installation Steps

If you prefer to set things up manually, or if the automated setup doesn't work for your environment, follow these steps:

Step 1: Clone the Repository

git clone https://github.com/robertguss/ai-starter-kit.git
cd ai-starter-kit

Or if you've already downloaded it:

cd ai-starter-kit

Step 2: Install Dependencies

pnpm install

This will install all required packages (~2-3 minutes depending on your internet speed).

Step 3: Initialize Convex

Run the following command to set up your Convex backend:

npx convex dev

What happens next:

You'll be prompted to log in or create a Convex account (free)
- Opens a browser window for authentication
- Sign up with GitHub, Google, or email
Choose to create a new project or link an existing one
- For first-time users, select "Create a new project"
- Give it a name (e.g., "ai-starter-kit-dev")
Convex will:
- Create a .env.local file with NEXT_PUBLIC_CONVEX_URL
- Start the Convex development server
- Begin watching for changes in your convex/ directory
Important: After Convex creates your .env.local file, you need to add NEXT_PUBLIC_CONVEX_SITE_URL:
- Open .env.local in your editor
- Add: NEXT_PUBLIC_CONVEX_SITE_URL=https://YOUR-DEPLOYMENT-NAME.convex.site
- Replace YOUR-DEPLOYMENT-NAME with your actual deployment name (same as in NEXT_PUBLIC_CONVEX_URL, but with .site instead of .cloud)
Warning: Do NOT set this to http://localhost:3000 - this will cause infinite loops and 500 errors!

Leave this terminal running! The Convex dev server needs to stay active.

Step 4: Set Environment Variables

Open a new terminal window (keep the Convex dev server running in the first one) and run:

# Generate and set a secure auth secret
npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32)

# Set your local development URL
npx convex env set SITE_URL http://localhost:3000

What these do:

BETTER_AUTH_SECRET: Encryption key for session tokens and hashes
SITE_URL: Base URL for authentication callbacks and redirects

Step 5: Start the Development Server

In your second terminal (or a third if you prefer), run:

pnpm run dev

This starts both:

Next.js frontend on http://localhost:3000
Convex backend (if not already running)

Verification

✅ Check That Everything Works

Open your browser to http://localhost:3000
- You should see the landing page
Create an account:
- Navigate to /signup or click "Sign Up"
- Enter an email and password (no email verification required)
- Submit the form
Log in:
- Navigate to /login or click "Log In"
- Use the credentials you just created
- You should be redirected to /dashboard
Verify Convex connection:
- Open the Convex Dashboard: https://dashboard.convex.dev
- Or run: npx convex dashboard
- You should see your project and the tables created by Better Auth

Run tests (optional but recommended):

# First, generate Convex types
npx convex codegen

# Run tests
pnpm run test:once

🎉 Success!

If you can sign up, log in, and see the dashboard, you're all set!

What's Next?

Now that you have the starter kit running, here are some suggested next steps:

1. Explore the Dashboard

Check out the sample charts and data
Navigate through the sidebar menu
Try the dark mode toggle

2. Review Example Code

Auth Components: components/login-form.tsx and components/signup-form.tsx
- Form handling and validation
- Better Auth integration
Protected Routes: middleware.ts
- See how route protection works

3. Read Detailed Documentation

Setup Guide - Detailed configuration options
Architecture Overview - System design and patterns
Development Guide - How to add features
Database Guide - Schema and data modeling

4. Make Your First Change

Try adding a new page:

# Create a new page
mkdir -p app/hello
echo 'export default function Hello() { return <h1>Hello, World!</h1> }' > app/hello/page.tsx

# Visit http://localhost:3000/hello

5. Add a New Convex Function

Create a new file convex/greetings.ts:

import { v } from "convex/values";
import { query } from "./_generated/server";

export const sayHello = query({
  args: { name: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    return `Hello, ${args.name}!`;
  },
});

Then in your React components, call it with:

import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";

const greeting = useQuery(api.greetings.sayHello, { name: "World" });

Troubleshooting Quick Setup

Problem: `npx convex dev` fails

Solution:

Make sure you're connected to the internet
Check that port 3210 isn't already in use
Try: npx convex dev --admin-key <key> if you have credentials

Problem: `NEXT_PUBLIC_CONVEX_URL` not found

Solution:

Make sure .env.local exists in the project root
Run npx convex dev again - it auto-generates this file
Restart your Next.js dev server after the file is created

Problem: "Unauthorized" or auth errors

Solution:

Verify environment variables are set:
```
npx convex env list
```
You should see BETTER_AUTH_SECRET and SITE_URL
Make sure SITE_URL matches your development URL (usually http://localhost:3000)

Problem: 500 errors on `/api/auth/get-session` (10+ second timeouts)

Cause: NEXT_PUBLIC_CONVEX_SITE_URL is set to localhost:3000 instead of your Convex site URL, causing an infinite loop.

Solution:

Open .env.local
Find NEXT_PUBLIC_CONVEX_SITE_URL
Change it from http://localhost:3000 to https://YOUR-DEPLOYMENT.convex.site
Restart your dev server

The .convex.site URL is your Convex HTTP endpoint - it should match your deployment name from NEXT_PUBLIC_CONVEX_URL but with .site instead of .cloud.

Problem: Port 3000 already in use

Solution:

Stop other processes on port 3000, or
Run Next.js on a different port:
```
pnpm run dev:frontend -- -p 3001
```

Update SITE_URL accordingly:

npx convex env set SITE_URL http://localhost:3001

Problem: Tests fail with "Cannot find _generated"

Solution:

Run Convex codegen first:
```
npx convex codegen
```
This generates TypeScript types needed for tests

Problem: `pnpm install` fails

Solution:

Try clearing the cache:
```
pnpm store prune
pnpm install --force
```
Or use npm instead:
```
npm install
```

Still Having Issues?

Check the Troubleshooting Guide for more solutions
Open an issue on GitHub
Review the Convex documentation

Summary Checklist

Next: Detailed Setup Guide →

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quick Start Guide

Table of Contents

Prerequisites

Required

Optional but Helpful

Automated Setup (Recommended)

Manual Installation Steps

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Initialize Convex

Step 4: Set Environment Variables

Step 5: Start the Development Server

Verification

✅ Check That Everything Works

🎉 Success!

What's Next?

1. Explore the Dashboard

2. Review Example Code

3. Read Detailed Documentation

4. Make Your First Change

5. Add a New Convex Function

Troubleshooting Quick Setup

Problem: `npx convex dev` fails

Problem: `NEXT_PUBLIC_CONVEX_URL` not found

Problem: "Unauthorized" or auth errors

Problem: 500 errors on `/api/auth/get-session` (10+ second timeouts)

Problem: Port 3000 already in use

Problem: Tests fail with "Cannot find _generated"

Problem: `pnpm install` fails

Still Having Issues?

Summary Checklist

FilesExpand file tree

QUICK_START.md

Latest commit

History

QUICK_START.md

File metadata and controls

Quick Start Guide

Table of Contents

Prerequisites

Required

Optional but Helpful

Automated Setup (Recommended)

Manual Installation Steps

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Initialize Convex

Step 4: Set Environment Variables

Step 5: Start the Development Server

Verification

✅ Check That Everything Works

🎉 Success!

What's Next?

1. Explore the Dashboard

2. Review Example Code

3. Read Detailed Documentation

4. Make Your First Change

5. Add a New Convex Function

Troubleshooting Quick Setup

Problem: npx convex dev fails

Problem: NEXT_PUBLIC_CONVEX_URL not found

Problem: "Unauthorized" or auth errors

Problem: 500 errors on /api/auth/get-session (10+ second timeouts)

Problem: Port 3000 already in use

Problem: Tests fail with "Cannot find _generated"

Problem: pnpm install fails

Still Having Issues?

Summary Checklist

Problem: `npx convex dev` fails

Problem: `NEXT_PUBLIC_CONVEX_URL` not found

Problem: 500 errors on `/api/auth/get-session` (10+ second timeouts)

Problem: `pnpm install` fails