ContextWeave

Environment Setup Guide for ContextWeave

This guide covers setting up environment variables and configuration for ContextWeave in different environments (development, staging, production).

Environment Variables Overview

ContextWeave uses environment variables for:

  • API Keys - External service authentication
  • Database Configuration - Supabase connection details
  • Feature Flags - Enable/disable functionality
  • Build Configuration - Deployment settings

Required Environment Variables

1. Core Application Variables

# Application Environment
NODE_ENV=development|staging|production
NEXT_TELEMETRY_DISABLED=1

# Supabase Configuration (Required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2. External API Keys (Optional but Recommended)

# Libraries.io API (for package information)
LIBS_IO_KEY=your_libraries_io_api_key

# Google APIs (for search functionality)
GOOGLE_API_KEY=AIzaSyC...
GOOGLE_CSE_ID=017576662512468239146:omuauf_lfve

# GitHub API (for repository information)
GH_PAT=ghp_your_github_personal_access_token

# OpenAI API (for AI features)
OPENAI_API_KEY=sk-your_openai_api_key

3. Optional Configuration

# RevenueCat (for subscription management)
NEXT_PUBLIC_REVENUECAT_API_KEY=your_revenuecat_key

# Analytics
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# Feature Flags
NEXT_PUBLIC_ENABLE_ANALYTICS=true
NEXT_PUBLIC_ENABLE_SUBSCRIPTIONS=false

Environment Setup by Platform

1. Development (Local)

Create .env.local file in project root:

# Copy from example
cp .env.example .env.local

# Edit with your values
# Bolt.new editor will show the file for editing

Minimal Development Setup:

# .env.local
NODE_ENV=development
NEXT_TELEMETRY_DISABLED=1

# Supabase (create free account at supabase.com)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key

# Optional: Add API keys for full functionality
LIBS_IO_KEY=your_key_here
GOOGLE_API_KEY=your_key_here
GH_PAT=your_token_here

2. Netlify Deployment

Set environment variables in Netlify dashboard:

# Go to: Site settings > Environment variables

# Required
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Build Configuration
NODE_VERSION=18
NPM_VERSION=9
NEXT_TELEMETRY_DISABLED=1

# Optional APIs
LIBS_IO_KEY=your_libraries_io_key
GOOGLE_API_KEY=your_google_key
GOOGLE_CSE_ID=your_cse_id
GH_PAT=your_github_token
OPENAI_API_KEY=your_openai_key

3. Vercel Deployment

Set environment variables in Vercel dashboard:

# Go to: Project Settings > Environment Variables

# Production Environment
NEXT_PUBLIC_SUPABASE_URL=https://prod-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=prod_anon_key

# Preview Environment (for staging)
NEXT_PUBLIC_SUPABASE_URL=https://staging-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=staging_anon_key

# Development Environment
NEXT_PUBLIC_SUPABASE_URL=https://dev-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=dev_anon_key

4. Railway (Backend)

If using the FastAPI backend:

# Railway environment variables
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=service_role_key
REDIS_URL=redis://localhost:6379

# External APIs
LIBS_IO_KEY=your_key
GOOGLE_API_KEY=your_key
GH_PAT=your_token
OPENAI_API_KEY=your_key

# AI Model Configuration
MODEL_PROFILE=gemini-pro-2.5
MODEL_ANSWER=deepseek-coder-r1-0528
EMBEDDING_MODEL=text-embedding-3-small

Getting API Keys

1. Supabase Setup

# 1. Go to supabase.com
# 2. Create new project
# 3. Go to Settings > API
# 4. Copy Project URL and anon key

# Example values:
NEXT_PUBLIC_SUPABASE_URL=https://abcdefghijklmnop.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFiY2RlZmdoaWprbG1ub3AiLCJyb2xlIjoiYW5vbiIsImlhdCI6MTY0MjU0ODAwMCwiZXhwIjoxOTU4MTI0MDAwfQ.signature

2. Libraries.io API Key

# 1. Go to libraries.io
# 2. Sign up/login
# 3. Go to Account Settings > API Key
# 4. Copy the API key

# Free tier: 1000 requests/month
# Paid tier: Higher limits available

3. Google API Setup

# 1. Go to Google Cloud Console
# 2. Create new project or select existing
# 3. Enable Custom Search API
# 4. Create credentials (API Key)
# 5. Create Custom Search Engine at cse.google.com

# Restrict API key to your domains for security

4. GitHub Personal Access Token

# 1. Go to GitHub Settings > Developer settings
# 2. Personal access tokens > Tokens (classic)
# 3. Generate new token
# 4. Select scopes: public_repo, read:user

# Token format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5. OpenAI API Key

# 1. Go to platform.openai.com
# 2. Sign up/login
# 3. Go to API Keys section
# 4. Create new secret key

# Token format: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Environment Variable Security

1. Public vs Private Variables

# ✅ Public (NEXT_PUBLIC_*) - Safe for browser
NEXT_PUBLIC_SUPABASE_URL=https://project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=anon_key
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# ✅ Private - Server-side only
SUPABASE_SERVICE_ROLE_KEY=service_role_key
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

# ❌ NEVER expose sensitive keys to client
# NEXT_PUBLIC_OPENAI_API_KEY=sk-... // DON'T DO THIS!

2. Key Rotation

# Regularly rotate sensitive keys
# 1. Generate new key in service dashboard
# 2. Update environment variables
# 3. Test application functionality
# 4. Revoke old key

# Set calendar reminders for quarterly rotation

3. Access Control

# Restrict API keys to specific domains/IPs
# Google API: Add HTTP referrer restrictions
# GitHub: Use minimal required scopes
# Supabase: Use RLS policies for data protection

Environment Validation

1. Runtime Validation

// lib/env-validation.ts
import { z } from 'zod'

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  NEXT_PUBLIC_SUPABASE_URL: z.string().url(),
  NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
  LIBS_IO_KEY: z.string().optional(),
  GOOGLE_API_KEY: z.string().optional(),
  GH_PAT: z.string().optional(),
  OPENAI_API_KEY: z.string().optional(),
})

export const env = envSchema.parse(process.env)

// Use in components
import { env } from '@/lib/env-validation'
console.log(env.NEXT_PUBLIC_SUPABASE_URL) // Type-safe access

2. Build-time Validation

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
  
  // Validate required environment variables
  async rewrites() {
    // Check required variables
    const requiredVars = [
      'NEXT_PUBLIC_SUPABASE_URL',
      'NEXT_PUBLIC_SUPABASE_ANON_KEY'
    ]
    
    for (const varName of requiredVars) {
      if (!process.env[varName]) {
        throw new Error(`Missing required environment variable: ${varName}`)
      }
    }
    
    return []
  },
}

module.exports = nextConfig

3. Development Checks

// lib/dev-checks.ts
export function validateDevelopmentEnvironment() {
  if (process.env.NODE_ENV === 'development') {
    const warnings = []
    
    if (!process.env.LIBS_IO_KEY) {
      warnings.push('LIBS_IO_KEY not set - library search will use fallback data')
    }
    
    if (!process.env.GOOGLE_API_KEY) {
      warnings.push('GOOGLE_API_KEY not set - search functionality limited')
    }
    
    if (!process.env.GH_PAT) {
      warnings.push('GH_PAT not set - GitHub integration disabled')
    }
    
    if (warnings.length > 0) {
      console.warn('⚠️ Development Environment Warnings:')
      warnings.forEach(warning => console.warn(`  • ${warning}`))
      console.warn('  See docs/bolt/environment-setup.md for setup instructions')
    }
  }
}

// Call in app initialization
validateDevelopmentEnvironment()

Testing Environment Variables

1. Local Testing

# Test environment loading
npm run dev

# Check in browser console
console.log(process.env.NEXT_PUBLIC_SUPABASE_URL)

# Test API functionality
fetch('/api/health').then(r => r.json()).then(console.log)

2. API Key Testing

# Test Libraries.io API
curl -H "Authorization: Bearer $LIBS_IO_KEY" \
  "https://libraries.io/api/search?q=react"

# Test Google Custom Search
curl "https://www.googleapis.com/customsearch/v1?key=$GOOGLE_API_KEY&cx=$GOOGLE_CSE_ID&q=react"

# Test GitHub API
curl -H "Authorization: Bearer $GH_PAT" \
  "https://api.github.com/user"

3. Supabase Connection Testing

// Test in browser console
import { supabase } from '@/lib/supabase'

// Test connection
supabase.auth.getSession().then(console.log)

// Test database query
supabase.from('libraries').select('*').limit(1).then(console.log)

// Test authentication
supabase.auth.signInWithOAuth({ provider: 'github' })

Troubleshooting

1. Common Issues

# Environment variables not loading
# 1. Check file name: .env.local (not .env)
# 2. Restart development server after changes
# 3. Verify no spaces around = sign
# 4. Check for typos in variable names

# Variables undefined in browser
# 1. Ensure NEXT_PUBLIC_ prefix for client-side variables
# 2. Check browser dev tools > Application > Local Storage
# 3. Verify build process includes variables

# API keys not working
# 1. Check key format and validity
# 2. Verify API key permissions/scopes
# 3. Check rate limits and quotas
# 4. Test keys manually with curl

2. Debug Commands

# Check environment variables
env | grep NEXT_PUBLIC
env | grep SUPABASE

# Test API endpoints
curl http://localhost:3000/api/health
curl http://localhost:3000/api/search-libraries?q=react

# Check build output
npm run build 2>&1 | grep -i error

3. Environment-specific Issues

# Development
# - Use .env.local for local overrides
# - Check file is in project root
# - Restart dev server after changes

# Staging/Production
# - Verify variables in deployment platform
# - Check for typos in variable names
# - Ensure proper escaping of special characters
# - Test with deployment preview

Best Practices

1. Organization

# Group related variables
# Database
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...

# External APIs
LIBS_IO_KEY=...
GOOGLE_API_KEY=...
GH_PAT=...

# Feature Flags
NEXT_PUBLIC_ENABLE_ANALYTICS=true
NEXT_PUBLIC_ENABLE_SUBSCRIPTIONS=false

2. Documentation

# Document each variable in .env.example
# Required for basic functionality
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Optional - enhances functionality
LIBS_IO_KEY=your_libraries_io_api_key  # For real package data
GOOGLE_API_KEY=your_google_api_key     # For enhanced search
GH_PAT=your_github_token               # For repository info

3. Validation

# Always validate environment variables
# Use TypeScript for type safety
# Fail fast if required variables missing
# Provide helpful error messages

This environment setup guide ensures ContextWeave works correctly across all deployment environments with proper configuration and security.