Environment Variables

Securely manage API keys, secrets, and configuration for your applications across different environments.

What are Environment Variables?

Environment variables are key-value pairs that store configuration and secrets outside your codebase. They allow you to customize your application's behavior without changing code.

Common Use Cases

API Keys & Secrets

Store sensitive credentials securely

Database URLs

Different databases for dev, staging, production

Feature Flags

Enable/disable features per environment

Configuration

App settings that change by environment

Adding Environment Variables

You can add environment variables through the dashboard or using the CLI.

Via Dashboard

Navigate to your project settings
Click on "Environment Variables"
Add your key-value pairs
Select which environments to apply to (Production, Preview, Development)
Click "Save"
Redeploy for changes to take effect

Via CLI

Add a single variable:

cupadev env add API_KEY your-secret-key --production

Import from .env file:

cupadev env pull

Environment Scopes

CupaDev supports three environment scopes, allowing you to use different values in each:

Production

Used for deployments from your main/master branch. These are your live production values.

DATABASE_URL=postgresql://prod.example.com

Preview

Used for all non-production branch deployments. Ideal for staging and testing.

DATABASE_URL=postgresql://staging.example.com

Development

Used when running your app locally with cupadev dev command.

DATABASE_URL=postgresql://localhost:5432

Built-in System Variables

CupaDev automatically injects these environment variables into all deployments:

Variable	Description
CUPADEV_ENV	production, preview, or development
CUPADEV_URL	The deployment URL
CUPADEV_GIT_COMMIT_SHA	Git commit hash
CUPADEV_GIT_COMMIT_MESSAGE	Git commit message
CUPADEV_GIT_BRANCH	Git branch name
CUPADEV_REGION	Deployment region

Accessing Variables in Code

How to access environment variables depends on your framework:

Next.js

Prefix with NEXT_PUBLIC_ for client-side access:

// Server-side
const apiKey = process.env.API_KEY;

// Client-side (must prefix with NEXT_PUBLIC_)
const publicKey = process.env.NEXT_PUBLIC_STRIPE_KEY;

Vite / React

Prefix with VITE_:

const apiUrl = import.meta.env.VITE_API_URL;

Node.js / Express

const dbUrl = process.env.DATABASE_URL;

Security Best Practices

Never Commit Secrets to Git

Never commit .env files or hardcode secrets in your source code. Always use environment variables.

Add to .gitignore:

.env
.env.local
.env.*.local

Sensitive Variables

Mark sensitive variables as "Secret" in the dashboard. They will be encrypted and hidden from logs.

• API keys and tokens
• Database credentials
• Private keys and certificates
• OAuth secrets

Rotate Secrets Regularly

Change your API keys and secrets periodically, especially if team members leave or if there's a potential security breach.

Use Different Keys Per Environment

Always use separate API keys and database credentials for production, preview, and development environments.

Troubleshooting

Variable is undefined in my app

Make sure you've added the variable to the correct environment scope and redeployed. For client-side access, remember to prefix with NEXT_PUBLIC_ or VITE_.

Changes not taking effect

Environment variables are injected at build time. You must trigger a new deployment for changes to apply.

How to update variables without redeploying?

Environment variables are set at build time and cannot be changed without redeployment. For runtime configuration, consider using a remote config service.