Skip to main content
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:
  1. Go to Project Settings → Environment Variables
  2. Add each variable for Production environment
  3. Redeploy to apply changes
Netlify:
  1. Go to Site Settings → Build & Deploy → Environment
  2. Add environment variables
  3. 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:
  1. Create separate deployments (e.g., separate Vercel projects)
  2. Configure different environment variables for each
  3. 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

Check that:
  • All required variables are set
  • Project ID is valid UUID format
  • API URL is valid HTTPS URL
  • No extra whitespace in values
Verify:
  • Developer key is correct
  • Project ID matches your Cloud Admin project
  • Project API key is active
  • Restart dev server after changing environment variables
  • 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