Environment Setup Guide

This document explains how to configure environment variables for the Kulcare Patient App.

Environment FilesCopy Anchor Link

.envCopy Anchor Link

Contains environment-specific configuration. Never commit this file - it's included in .gitignore.

.env.exampleCopy Anchor Link

Template file showing all available environment variables with descriptions. This file is committed to the repository.

Getting StartedCopy Anchor Link

1. Copy the example file:

   Copy Text

   cp .env.example .env

2. Fill in the actual values for your environment:

   Copy Text

   # Edit .env with your actual values
   nano .env

Environment VariablesCopy Anchor Link

API ConfigurationCopy Anchor Link

Third-party ServicesCopy Anchor Link

Security & EncryptionCopy Anchor Link

Environment & ReleaseCopy Anchor Link

Environment-Specific ConfigurationCopy Anchor Link

DevelopmentCopy Anchor Link

VITE_API_BASE_URL=https://api-stg.kulcare.com
VITE_ENVIRONMENT=development
VITE_DEBUG=true

StagingCopy Anchor Link

VITE_API_BASE_URL=https://api-stg.kulcare.com
VITE_ENVIRONMENT=staging
VITE_DEBUG=false

ProductionCopy Anchor Link

VITE_API_BASE_URL=https://api.kulcare.com
VITE_ENVIRONMENT=production
VITE_DEBUG=false

API Proxy ConfigurationCopy Anchor Link

In development, the app uses a Vite proxy to avoid CORS issues:

// vite.config.ts
server: {
  proxy: {
    '/api': {
      target: process.env.VITE_API_BASE_URL || 'https://api-stg.kulcare.com',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
      secure: true,
    },
  },
}

This means:

• Development: API calls go to /api/* → proxied to the actual API server
• Production: API calls go directly to VITE_API_BASE_URL

Type-Safe Environment AccessCopy Anchor Link

Use the env utility for type-safe environment variable access:

import { env } from '@/lib/env';

// Type-safe access
const apiUrl = env.API_BASE_URL;
const isDebug = env.DEBUG;
const environment = env.ENVIRONMENT; // 'development' | 'staging' | 'production'

ValidationCopy Anchor Link

Environment variables are automatically validated on app startup in development mode. Missing required variables will throw an error.

Security Best PracticesCopy Anchor Link

1. Never commit .env files with real credentials
2. Use different keys for each environment
3. Rotate secrets regularly
4. Limit access to production environment variables
5. Use secure key management for production (e.g., AWS Secrets Manager)

TroubleshootingCopy Anchor Link

API Connection IssuesCopy Anchor Link

1. Check the browser console for configuration logs (development mode only)
2. Verify the API URL is accessible
3. Check if CORS is properly configured on the backend
4. Ensure the Vite proxy is working correctly

Missing Environment VariablesCopy Anchor Link

If you see errors about missing environment variables:

1. Check that .env file exists
2. Verify variable names use the VITE_ prefix
3. Ensure no spaces around the = sign in .env
4. Restart the development server after changing .env

Environment Not LoadingCopy Anchor Link

If environment variables aren't being picked up:

1. Restart the development server
2. Check the .env file is in the correct location (project root)
3. Verify variable names are exactly as documented
4. Check for any syntax errors in the .env file