> ## Documentation Index
> Fetch the complete documentation index at: https://devkit4ai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development Guide

> Set up your local environment and run the Starter Kit with the hosted Cloud API or a local backend.

<Info>
  **Prerequisites**:

  * Node.js 19 or later
  * A GitHub account
  * Cloud Admin access at [devkit4ai.com/console](https://devkit4ai.com/console) or [vibecoding.ad/console](https://vibecoding.ad/console)
  * Make (or npm) for running commands
</Info>

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:

<Steps>
  <Step title="Clone the Starter Kit">
    ```bash theme={null}
    git clone https://github.com/VibeCodingStarter/starter-kit.git
    cd starter-kit
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    make install   # or npm install
    ```
  </Step>

  <Step title="Configure environment">
    Create `.env.local` with your Cloud Admin credentials:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Start development server">
    ```bash theme={null}
    make dev   # starts on port 3004
    ```

    Visit `http://localhost:3004` and sign in with your Cloud Admin credentials.
  </Step>
</Steps>

## 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

```bash theme={null}
# 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

```bash theme={null}
# 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](/starter-kit/customization/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](/starter-kit/customization/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](/starter-kit/advanced/api-integration) for advanced patterns.

## Advanced: Local Backend Development

<Warning>
  Only needed if you're contributing to the Dev Kit for AI platform itself. Most developers should use the hosted Cloud API.
</Warning>

If you need to run the backend locally:

<Steps>
  <Step title="Prerequisites">
    Install additional requirements:

    * Python 3.13 with virtualenv
    * Docker Desktop for PostgreSQL and Redis
    * Git access to the private devkit4ai repository
  </Step>

  <Step title="Clone and setup backend">
    ```bash theme={null}
    git clone [private-repo-url] devkit4ai
    cd devkit4ai/backend-api
    make setup
    make start-services  # starts PostgreSQL and Redis
    make dev            # starts API on port 8000
    ```
  </Step>

  <Step title="Point Starter Kit to local backend">
    Update your `.env.local`:

    ```bash theme={null}
    NEXT_PUBLIC_API_URL=http://localhost:8000
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Configuration errors shown in banner" icon="triangle-exclamation">
    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
  </Accordion>

  <Accordion title="Cannot connect to Cloud API" icon="cloud-exclamation">
    Verify:

    * Your internet connection is working
    * `NEXT_PUBLIC_API_URL` is correct ([https://api.vibecoding.ad](https://api.vibecoding.ad))
    * Your credentials are valid in Cloud Admin
    * No firewall blocking the connection
  </Accordion>

  <Accordion title="Port 3004 already in use" icon="plug">
    Either stop the existing process or change the port:

    ```bash theme={null}
    # Find and kill process
    lsof -ti:3004 | xargs kill

    # Or change port in package.json dev script
    ```
  </Accordion>

  <Accordion title="npm install fails" icon="package">
    Ensure you're using Node.js 19 or later:

    ```bash theme={null}
    node --version  # should be v19.0.0 or higher
    ```

    Try clearing npm cache:

    ```bash theme={null}
    npm cache clean --force
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Customize Your App" icon="palette" href="/starter-kit/customization/branding-styling">
    Update branding, colors, and styling to match your product
  </Card>

  <Card title="Add Authentication" icon="lock" href="/starter-kit/auth/registration-login">
    Configure user registration and login flows
  </Card>

  <Card title="Deploy to Production" icon="rocket" href="/starter-kit/deployment/production-build">
    Deploy to Vercel, Netlify, or your hosting provider
  </Card>

  <Card title="Explore Components" icon="box" href="/starter-kit/customization/component-library">
    Browse the built-in UI component library
  </Card>
</CardGroup>