Contributing to ZapDev

Guidelines for contributing to the ZapDev AI-powered development platform

Welcome Contributors

Thank you for your interest in contributing to ZapDev! This guide will help you get started with contributing to our AI-powered development platform.

Getting Started

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

• Bun (package manager - required)
• Docker (for E2B template builds)
• Node.js 18+ (for compatibility)
• PostgreSQL or access to a database URL

Initial Setup

1. Fork and Clone

   Fork the repository on GitHub and clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/zapdev.git
   cd zapdev
   
2. Install Dependencies

   Install all project dependencies using Bun:

   bun install
   

   NEVER use npm, pnpm, or yarn for this project. Always use bun as the package manager.

3. Configure Environment

   Copy the example environment file and fill in your credentials:

   cp env.example .env
   

   Required environment variables:

   • DATABASE_URL - PostgreSQL connection string
   • OPENROUTER_API_KEY - Vercel AI Gateway key
   • E2B_API_KEY - E2B sandbox API key
   • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Clerk auth public key
   • CLERK_SECRET_KEY - Clerk auth secret key
   • INNGEST_EVENT_KEY - Inngest event key
   • INNGEST_SIGNING_KEY - Inngest signing key
4. Build E2B Template

   Before running the application, build the E2B sandbox template:

   # Install E2B CLI
   npm 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 your-template-name --cmd "/compile_page.sh"
   

   After building, update the template name in src/inngest/functions.ts:22

5. Start Development Servers

   Run the development servers in two separate terminals:

   Terminal 1 - Next.js:

   bun run dev
   

   Terminal 2 - Convex Backend:

   bun run convex:dev
   

Development Workflow

Making Changes

1. Create a Feature Branch

   git checkout -b feature/your-feature-name
   

2. Make Your Changes

   • Follow the code conventions (see conventions.mdx)
   • Write tests for new features
   • Ensure your changes don’t break existing tests

3. Run Tests

   bun run test
   

4. Run Linter

   bun run lint
   

5. Build Locally

   bun run build
   

Commit Guidelines

We follow conventional commit messages:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Test additions or changes
• chore: - Build process or auxiliary tool changes

Examples:

git commit -m "feat: add framework selection dialog"
git commit -m "fix: resolve E2B sandbox timeout issue"
git commit -m "docs: update contributing guidelines"

Pull Request Process

1. Push Your Changes

   git push origin feature/your-feature-name
   
2. Create Pull Request

   • Go to the repository on GitHub
   • Click “New Pull Request”
   • Select your feature branch
   • Fill in the PR template with:
     • Description of changes
     • Related issue numbers
     • Screenshots (if UI changes)
     • Testing performed
3. Code Review

   • Address reviewer feedback
   • Push additional commits if needed
   • Ensure CI checks pass
4. Merge

   Once approved, a maintainer will merge your PR

Project Structure

Understanding the codebase structure will help you navigate and contribute effectively:

./
├── src/
│   ├── app/              # Next.js 15 App Router pages
│   ├── modules/          # Feature modules (home, projects, messages, usage)
│   ├── agents/           # AI agent orchestration (SSE path)
│   ├── inngest/          # Inngest + Agent Kit background workflows
│   ├── prompts/          # Framework-specific LLM prompts
│   ├── components/ui/    # Shadcn/ui components
│   ├── lib/              # Utilities, framework config
│   └── trpc/             # Type-safe API (client/server)
├── convex/               # Real-time database (schema, queries, mutations)
├── sandbox-templates/    # E2B sandbox configs (nextjs, angular, react, vue, svelte)
├── tests/                # Jest test suite with mocks
└── explanations/         # Documentation (ALL .md files go here)

Where to Contribute

Areas We Need Help

• Bug Fixes - Check the issues labeled bug
• Features - Look for issues labeled enhancement
• Documentation - Help improve our docs (issues labeled documentation)
• Tests - Increase test coverage
• Performance - Optimize E2B sandbox initialization
• Framework Support - Improve Angular, Vue, Svelte, React templates

Good First Issues

Look for issues labeled good first issue - these are great for newcomers!

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on the code, not the person
• Help create a welcoming environment for all contributors

Getting Help

• Questions? Open a discussion on GitHub
• Bugs? Open an issue with reproduction steps
• Feature Ideas? Open an issue with your proposal

Additional Resources

• Testing Guide - Learn about our testing setup
• Code Conventions - Follow our coding standards
• Development Guide - Technical development details
• README - Project overview

---

Thank you for contributing to ZapDev! Your efforts help make AI-powered development accessible to everyone.