Deployment Configuration - Dev Kit for AI

The Starter Kit uses environment variables to configure how it connects to the Cloud API and what features are available.

Configuration basics

Your application requires these environment variables:

.env.local

# Deployment mode (always "project" for Starter Kit)
DEVKIT4AI_MODE=project

# Cloud API endpoint
NEXT_PUBLIC_API_URL=https://api.vibecoding.ad

# Your credentials from Cloud Admin
DEVKIT4AI_DEVELOPER_KEY=dk_your_developer_key
DEVKIT4AI_PROJECT_ID=your-project-uuid
DEVKIT4AI_PROJECT_KEY=ak_your_api_key

Environment-specific configuration

Local development

.env.local

DEVKIT4AI_MODE=project
NEXT_PUBLIC_API_URL=https://api.vibecoding.ad
DEVKIT4AI_DEVELOPER_KEY=dk_dev_...
DEVKIT4AI_PROJECT_ID=...
DEVKIT4AI_PROJECT_KEY=ak_dev_...
ENVIRONMENT=local

Staging deployment

.env.staging

DEVKIT4AI_MODE=project
NEXT_PUBLIC_API_URL=https://api.vibecoding.ad
DEVKIT4AI_DEVELOPER_KEY=dk_staging_...
DEVKIT4AI_PROJECT_ID=...
DEVKIT4AI_PROJECT_KEY=ak_staging_...
ENVIRONMENT=staging

Production deployment

Never commit production credentials to version control. Use your hosting provider’s environment variable system.

Vercel:

Go to Project Settings → Environment Variables
Add each variable for Production environment
Redeploy to apply changes

Netlify:

Go to Site Settings → Build & Deploy → Environment
Add environment variables
Trigger new deploy

Other platforms: Follow your platform’s documentation for setting environment variables.

Configuration validation

The Starter Kit automatically validates configuration on startup via lib/deployment-mode.ts:

lib/deployment-mode.ts

export async function hydrateDeploymentMode() {
  const issues: ConfigIssue[] = []
  
  // Validate required variables
  if (!process.env.DEVKIT4AI_MODE) {
    issues.push({
      severity: 'error',
      message: 'DEVKIT4AI_MODE is required'
    })
  }
  
  // Validate project ID format
  const projectId = process.env.DEVKIT4AI_PROJECT_ID
  if (projectId && !isValidUUID(projectId)) {
    issues.push({
      severity: 'error',
      message: 'DEVKIT4AI_PROJECT_ID must be a valid UUID'
    })
  }
  
  return {
    mode: process.env.DEVKIT4AI_MODE,
    backendApiUrl: process.env.NEXT_PUBLIC_API_URL,
    issues,
    isReady: issues.filter(i => i.severity === 'error').length === 0
  }
}

Runtime configuration access

Server Components

import { hydrateDeploymentMode } from '@/lib/deployment-mode'

export default async function Page() {
  const config = await hydrateDeploymentMode()
  
  if (!config.isReady) {
    return <ConfigurationError issues={config.issues} />
  }
  
  // Use config.backendApiUrl, config.headers
}

Client Components

'use client'

import { useDeploymentMode } from '@/lib/auth-context'

export function MyComponent() {
  const config = useDeploymentMode()
  
  // Access config.backendApiUrl, config.headers, config.isReady
}

Server Actions

'use server'

import { hydrateDeploymentMode } from '@/lib/deployment-mode'

export async function myAction() {
  const config = await hydrateDeploymentMode()
  
  await fetch(`${config.backendApiUrl}/api/endpoint`, {
    headers: config.headers
  })
}

Request headers

The configuration automatically constructs required headers:

const headers = {
  'X-User-Role': 'end_user',
  'X-Developer-Key': process.env.DEVKIT4AI_DEVELOPER_KEY,
  'X-Project-ID': process.env.DEVKIT4AI_PROJECT_ID,
  'X-API-Key': process.env.DEVKIT4AI_PROJECT_KEY
}

These headers authenticate your requests to the Cloud API.

Multi-project setup

To deploy the same codebase for multiple projects:

Create separate deployments (e.g., separate Vercel projects)
Configure different environment variables for each
Each deployment gets its own PROJECT_ID and PROJECT_KEY

Example:

# Project A (app-a.vercel.app)
DEVKIT4AI_PROJECT_ID=uuid-for-project-a
DEVKIT4AI_PROJECT_KEY=pk_project_a_key

# Project B (app-b.vercel.app)  
DEVKIT4AI_PROJECT_ID=uuid-for-project-b
DEVKIT4AI_PROJECT_KEY=pk_project_b_key

Troubleshooting

Configuration errors on startup

Check that:

All required variables are set
Project ID is valid UUID format
API URL is valid HTTPS URL
No extra whitespace in values

API calls return 401 Unauthorized

Verify:

Developer key is correct
Project ID matches your Cloud Admin project
Project API key is active
Restart dev server after changing environment variables

Environment variables not updating

Clear Next.js cache: rm -rf .next
Restart development server
For production: trigger new deployment

Next steps

Environment Variables

Complete variable reference

Deploy

Deploy to production

​Configuration basics

​Environment-specific configuration

​Local development

​Staging deployment

​Production deployment

​Configuration validation

​Runtime configuration access

​Server Components

​Client Components

​Server Actions

​Request headers

​Multi-project setup

​Troubleshooting

​Next steps

Environment Variables

Deploy

Configuration basics

Environment-specific configuration

Local development

Staging deployment

Production deployment

Configuration validation

Runtime configuration access

Server Components

Client Components

Server Actions

Request headers

Multi-project setup

Troubleshooting

Next steps