Skip to main content

​
Quick Start Guide

Get ZapDev running locally in under 5 minutes. This guide covers the essentials to create your first AI-generated application.
For detailed setup including all environment variables and optional services, see the Installation Guide.

​
Prerequisites

Before starting, ensure you have:
  • Node.js 18+ installed
  • Bun package manager (curl -fsSL https://bun.sh/install | bash)
  • Docker installed and running (required for E2B template building)
  • Git for cloning the repository

​
Installation

1

Clone the Repository

git clone https://github.com/yourusername/zapdev.git
cd zapdev
2

Install Dependencies

ZapDev uses Bun as the package manager:
bun install
Always use bun instead of npm, pnpm, or yarn. The project is optimized for Bun.
3

Set Up Environment Variables

Copy the example environment file and configure essential variables:
cp env.example .env
Edit .env and add these required variables:
# Required: Convex Database
NEXT_PUBLIC_CONVEX_URL="https://your-project.convex.cloud"

# Required: Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."
CLERK_JWT_ISSUER_DOMAIN="your-clerk-domain.clerk.accounts.dev"

# Required: OpenRouter for AI Models
OPENROUTER_API_KEY="sk-or-v1-..."

# Required: E2B Sandboxes
E2B_API_KEY="e2b_..."
Get free API keys from:
4

Set Up Convex Database

Initialize and start the Convex development server:
# Login to Convex
bunx convex dev
Follow the prompts to create a new project or link to an existing one. This will populate NEXT_PUBLIC_CONVEX_URL automatically.
Keep the Convex dev server running in a separate terminal throughout development.
5

Build E2B Template

Build the sandbox template that AI agents use to create applications:
# Install E2B CLI globally
bun i -g @e2b/cli

# Login to E2B
e2b auth login

# Navigate to template directory
cd sandbox-templates/nextjs

# Build the template
e2b template build --name zapdev-sandbox --cmd "/compile_page.sh"

# Go back to project root
cd ../..
The E2B template build requires Docker to be running. This step is required before running the application.
6

Update Template Name in Code

After building your template, update the template name in the code:Open src/inngest/functions/code-agent.ts and update line 22:
// Replace "zapdev" with your template name
const sandbox = await Sandbox.create("zapdev-sandbox");
7

Start Development Server

In a new terminal (keeping Convex dev server running), start the Next.js development server:
bun run dev
Your application will be available at http://localhost:3000

​
Create Your First Project

Now that ZapDev is running, let’s create your first AI-generated application:
1

Sign Up / Sign In

Navigate to http://localhost:3000 and create an account using Clerk authentication.
2

Create a New Project

Click “New Project” and provide:
  • Project Name: e.g., “My Todo App”
  • Framework: Select Next.js (or your preferred framework)
  • Description: Describe what you want to build
Example description:
Create a simple todo application with the ability to add, 
complete, and delete tasks. Use a clean, modern design with 
Tailwind CSS.
3

Watch AI Generate Code

The AI agent will:
  • Create an E2B sandbox
  • Generate project files
  • Set up the development environment
  • Build and start the application
You’ll see real-time updates in the chat interface:
// Stream events show progress
{
  type: "file-created",
  data: {
    path: "app/page.tsx",
    content: "...",
    size: 1024
  }
}
4

Preview Your Application

Once generation completes, you’ll see:
  • Live Preview: Your running application
  • File Explorer: Browse generated files
  • Code Editor: View and understand the code
5

Iterate and Refine

Continue the conversation to make changes:
  • “Add a filter to show only completed tasks”
  • “Change the color scheme to dark mode”
  • “Add persistence using local storage”
The AI will update the code in real-time while maintaining your application’s functionality.

​
Understanding the Architecture

ZapDev uses a feature-based module structure: 
// Feature modules with co-located UI and server logic
src/
├── modules/
│   ├── projects/
│   │   ├── ui/              # React components
│   │   └── server/          # tRPC procedures
│   ├── messages/
│   │   ├── ui/
│   │   └── server/
│   └── usage/
│       ├── ui/
│       └── server/
├── agents/                  # AI orchestration
├── inngest/                 # Background jobs
└── trpc/                    # API router

​
Key Components

Convex Database

Real-time reactive database with automatic subscriptions

tRPC API

Type-safe API layer with automatic TypeScript inference

E2B Sandboxes

Isolated environments for safe code execution

AI Agents

Orchestrate code generation with streaming updates

​
Usage Limits

ZapDev includes built-in usage tracking: 
// Free tier: 5 generations per day
// Pro tier: 100 generations per day
// Unlimited tier: No limits
Track your usage in the dashboard or upgrade to Pro for higher limits.

​
Common Commands

# Terminal 1: Convex backend
bun run convex:dev

# Terminal 2: Next.js frontend
bun run dev

​
Troubleshooting

​
E2B Template Build Fails

Ensure Docker is running: 
docker ps
If Docker isn’t running, start it and retry the template build.

​
Convex Connection Issues

Verify your Convex URL is set correctly: 
echo $NEXT_PUBLIC_CONVEX_URL
Restart the Convex dev server if needed: 
bun run convex:dev

​
AI Generation Errors

Check your OpenRouter API key and credits:
  • Visit OpenRouter Dashboard
  • Ensure your key has sufficient credits
  • Verify the key is correctly set in .env

​
Next Steps

Full Installation Guide

Complete setup with all environment variables and optional services

Framework Guide

Learn about supported frameworks and their configurations

API Reference

Explore the tRPC API and database schema

Deployment

Deploy ZapDev to Vercel or your preferred platform

Build docs developers (and LLMs) love

Get started for freeTalk to us