Skip to main content

​
Overview

Environment variables allow you to store configuration values and secrets that your application needs to run. Common use cases include:
  • API keys and tokens
  • External service credentials
  • Feature flags
  • Environment-specific configuration
In Stardeck, environment variables can be configured per project and targeted to specific deployment environments.

​
Deployment Targets

Each environment variable can be configured for one or more deployment targets:

​
Sandbox

The development environment where you build and test your application. When you modify sandbox environment variables, the dev server automatically restarts to apply the changes.

​
Preview

Branch preview deployments that are created for specific Git branches. Use preview variables to test with production-like data without affecting your live site.

​
Production

Your live, published application. Production variables are used when you deploy your project to your custom domain or the default project-slug.stardeck.site URL.
You can select multiple targets for a single variable, allowing you to reuse the same configuration across environments.

​
Variable Types

Stardeck supports two types of environment variables with different visibility and access patterns:

​
Non-Secret Variables

Non-secret variables are suitable for non-sensitive configuration values that can be safely exposed:
  • Build-time access: Automatically available to Vite with VITE_ prefix during the build process
  • Runtime access: Available as regular environment variables
  • Visibility: Values are visible (but obscured) in the project settings UI
  • Use cases: Public API endpoints, feature flags, non-sensitive configuration
When you create a non-secret variable named API_URL, Stardeck automatically makes it available as both VITE_API_URL (for client-side code) and API_URL (for server-side code).

​
Secret Variables

Secret variables are encrypted and kept secure:
  • Runtime-only: Only available at runtime, never exposed during the build process
  • Encrypted storage: Values are encrypted in the database
  • Hidden in UI: Values are never displayed in the project settings
  • Use cases: API keys, tokens, passwords, database credentials
Secret variables are not accessible to Vite during the build step. They are only available to your server-side code at runtime via process.env.

​
Reserved Variables

Certain environment variable names are reserved by Stardeck for system use and cannot be set by users:

​
Reserved Prefixes

  • VITE_ - Automatically added to non-secret variables for client-side access. You should never create variables starting with VITE_ as Stardeck handles this automatically.
  • OIDC_ - Reserved for OAuth and authentication configuration managed by Stardeck

​
Reserved Names

  • DATABASE_URL - Managed database connection string (automatically provided by Stardeck)
  • APP_DATABASE_NAME - Application database name
  • DATABASE_NAME - Database name (legacy)
  • DEPLOYMENT_ID - Current deployment identifier
  • CLOUDFLARE_INCLUDE_PROCESS_ENV - Cloudflare environment flag
If you try to create a variable with a reserved name, you’ll receive an error. Choose different names for your custom variables (e.g., use EXTERNAL_DATABASE_URL instead of DATABASE_URL for third-party database connections).

​
Managing Environment Variables

​
Accessing the Settings

  1. Open your project in the Stardeck dashboard
  2. Click the Settings button (gear icon)
  3. Navigate to the Environment Variables tab

​
Adding a Variable

  1. Click Add Environment Variable
  2. Enter a Key in UPPERCASE_WITH_UNDERSCORES format (e.g., API_KEY, STRIPE_SECRET_KEY)
  3. Enter the Value
  4. Toggle Secret Variable if the value contains sensitive information
  5. Select one or more Deployment Targets (sandbox, preview, production)
  6. Click Add Variable
For sandbox environments, the dev server will automatically restart to apply new environment variables.

​
Editing a Variable

  1. Click Edit on the variable you want to modify
  2. Update the key, value, secret status, or deployment targets
  3. Click Update Variable
When editing a secret variable, leave the value field empty to keep the existing secret value unchanged.

​
Deleting a Variable

  1. Click the trash icon next to the variable you want to remove
  2. Confirm the deletion
Deleting an environment variable will trigger a dev server restart for sandbox environments if applicable.

​
Using Variables in Your Code

​
Client-Side Code (Vite/React)

Access non-secret variables in your client-side code using import.meta.env: 
// Accessing a non-secret variable
const apiUrl = import.meta.env.VITE_API_URL;
const featureFlag = import.meta.env.VITE_ENABLE_FEATURE;

console.log(`API URL: ${apiUrl}`);
Only variables prefixed with VITE_ are accessible in client-side code. Never store secrets in VITE_ variables as they are embedded in your built application.

​
Server-Side Code (Node.js/API Routes)

Access both secret and non-secret variables in your server code using process.env: 
// Server-side API route
export async function POST(req: Request) {
  // Access secret variables
  const apiKey = process.env.STRIPE_SECRET_KEY;
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
  
  // Access non-secret variables
  const apiUrl = process.env.EXTERNAL_API_URL;
  
  // Use the variables
  const response = await fetch(apiUrl, {
    headers: { Authorization: `Bearer ${apiKey}` }
  });
  
  return Response.json({ data: await response.json() });
}

​
Best Practices

​
Naming Conventions

  • Use UPPERCASE letters with underscores: MY_API_KEY, DATABASE_URL
  • Be descriptive and consistent: STRIPE_SECRET_KEY, STRIPE_PUBLIC_KEY
  • Follow your team’s naming patterns

​
Security

  • Use secrets for sensitive data: API keys, tokens, passwords, and connection strings should always be marked as secret
  • Never commit secrets: Don’t store sensitive values in your Git repository
  • Rotate credentials: Periodically update secret values, especially if they may have been exposed
  • Limit access: Only add environment variables to the targets where they’re needed

​
Organization

  • Group related variables: Use prefixes to organize related configuration (e.g., STRIPE_, AWS_)
  • Document variables: Keep track of what each variable is used for
  • Environment parity: Use the same variable names across all targets with environment-specific values

​
Client-Side Variables

  • Minimize client exposure: Only use VITE_ variables when the value needs to be accessible in the browser
  • Never expose secrets: Client-side code is visible to users, so never put sensitive data in VITE_ variables
  • Validate on server: Always validate client-provided data on the server, even if you have client-side checks
Remember: Non-secret variables are automatically available with the VITE_ prefix for client-side access. You don’t need to create separate variables.

​
Common Patterns

​
API Configuration

// Non-secret variable for API endpoint
EXTERNAL_API_URL=https://api.example.com

// Secret variable for API key (server-side only)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

​
External Database Configuration

// Secret variable for external database connection
EXTERNAL_DATABASE_URL=postgresql://user:pass@host:5432/db

// Non-secret variable for connection pool size
EXTERNAL_DB_POOL_SIZE=10
Stardeck automatically provides DATABASE_URL for your project’s managed database. Use EXTERNAL_DATABASE_URL or similar names for connecting to external databases.

​
Feature Flags

// Non-secret variables for feature toggles
VITE_ENABLE_ANALYTICS=true
VITE_ENABLE_BETA_FEATURES=false

​
Environment-Specific Configuration

Set different values for the same variable across targets:
  • Sandbox: EXTERNAL_API_URL=http://localhost:8000
  • Preview: EXTERNAL_API_URL=https://api-staging.example.com
  • Production: EXTERNAL_API_URL=https://api.example.com
Need help with environment variables? Contact our support team through your dashboard.