Skip to main content
Prerequisites:
This guide helps you set up a productive local development environment for building with the Starter Kit. You can connect to the hosted Cloud API for the fastest setup, or run a local backend if you’re contributing to the platform itself.

​
Quick Start with Hosted Cloud API

The recommended approach for most developers is to use the hosted Cloud API:
1

Clone the Starter Kit

git clone https://github.com/VibeCodingStarter/starter-kit.git
cd starter-kit
2

Install dependencies

make install   # or npm install
3

Configure environment

Create .env.local with your Cloud Admin credentials:
DEVKIT4AI_MODE=project
NEXT_PUBLIC_API_URL=https://api.vibecoding.ad
DEVKIT4AI_DEVELOPER_KEY=dk_your_developer_key
DEVKIT4AI_PROJECT_ID=your-project-uuid
DEVKIT4AI_PROJECT_KEY=pk_your_project_key
Get these values from your Cloud Admin dashboard.
4

Start development server

make dev   # starts on port 3004
Visit http://localhost:3004 and sign in with your Cloud Admin credentials.

​
Development Workflow

​
Making Changes

The Starter Kit is built with Next.js 15 and React 19 Server Components:
  • Components are in components/ (ui, generic, project folders)
  • Pages use the App Router in app/
  • Styles use Tailwind CSS with dark mode support
  • Configuration is in config/app.config.ts
When you save changes, Turbopack automatically reloads your browser.

​
Testing Your Changes

# Run all tests
npm run test

# Run integration tests with Vitest
npm run test:integration

# Run E2E tests with Playwright
npm run test:e2e

# Lint your code
npm run lint

​
Building for Production

# Create production build
npm run build

# Test production build locally
npm run start

​
Customization Guide

​
Update Branding

  1. Edit config/app.config.ts to change app name and description
  2. Replace logo files in public/
  3. Update colors in tailwind.config.ts
  4. Modify components/project/header.tsx and footer.tsx
See the Branding & Styling guide for details.

​
Add New Features

  1. Create new pages in app/ following Next.js App Router conventions
  2. Use Server Components by default for better performance
  3. Add “use client” only when you need interactivity
  4. Reference existing patterns in app/dashboard/page.tsx
See Custom Pages for examples.

​
Connect to Cloud API

All API calls use the configuration from lib/deployment-mode.ts:
  • Authentication headers are automatically added
  • Server Actions in app/actions.ts handle login/registration
  • The deployment mode validates your environment variables
See API Integration for advanced patterns.

​
Advanced: Local Backend Development

Only needed if you’re contributing to the Dev Kit for AI platform itself. Most developers should use the hosted Cloud API.
If you need to run the backend locally:
1

Prerequisites

Install additional requirements:
  • Python 3.13 with virtualenv
  • Docker Desktop for PostgreSQL and Redis
  • Git access to the private devkit4ai repository
2

Clone and setup backend

git clone [private-repo-url] devkit4ai
cd devkit4ai/backend-api
make setup
make start-services  # starts PostgreSQL and Redis
make run            # starts API on port 8000
3

Point Starter Kit to local backend

Update your .env.local:
NEXT_PUBLIC_API_URL=http://localhost:8000

​
Troubleshooting

The amber banner indicates environment variable issues. Check:
  • All required variables are set in .env.local
  • DEVKIT4AI_PROJECT_ID is a valid UUID format
  • No quotes around values
  • Developer key and project key are not mixed up
Verify:
  • Your internet connection is working
  • NEXT_PUBLIC_API_URL is correct (https://api.vibecoding.ad)
  • Your credentials are valid in Cloud Admin
  • No firewall blocking the connection
Either stop the existing process or change the port:
# Find and kill process
lsof -ti:3004 | xargs kill

# Or change port in package.json dev script
Ensure you’re using Node.js 19 or later:
node --version  # should be v19.0.0 or higher
Try clearing npm cache:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Customize Your App

Update branding, colors, and styling to match your product

Add Authentication

Configure user registration and login flows

Deploy to Production

Deploy to Vercel, Netlify, or your hosting provider

Explore Components

Browse the built-in UI component library