> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Learn how to configure and manage environment variables for your Stardeck apps

## 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 app and targeted to specific deployment environments.

## Deployment Targets

Each environment variable can be configured for one or more deployment targets. For a complete overview of how environments work and why data stays separate between them, see [Environments](/environments).

### 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

Preview deployments for testing changes before going live. 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 app to your custom domain or the default `app-slug.stardeck.site` URL.

<Note>
  You can select multiple targets for a single variable, allowing you to reuse the same
  configuration across environments.
</Note>

## 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 app settings UI
* **Use cases**: Public API endpoints, feature flags, non-sensitive configuration

<Info>
  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).
</Info>

### 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 app settings
* **Use cases**: API keys, tokens, passwords, database credentials

<Warning>
  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`.
</Warning>

## 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

<Warning>
  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).
</Warning>

## Managing Environment Variables

### Accessing the Settings

1. Open your app in the Stardeck dashboard
2. Click the **Settings** button (gear icon)
3. Navigate to the [**Environment Variables** tab](https://www.stardeck.ai/projects/~/dashboard/config/env)

### 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**

<Note>
  For sandbox environments, the dev server will automatically restart to apply new environment
  variables.
</Note>

### 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**

<Info>
  When editing a secret variable, leave the value field empty to keep the existing secret value
  unchanged.
</Info>

### Deleting a Variable

1. Click the **trash icon** next to the variable you want to remove
2. Confirm the deletion

<Warning>
  Deleting an environment variable will trigger a dev server restart for sandbox environments if
  applicable.
</Warning>

## Using Variables in Your Code

### Client-Side Code (Vite/React)

Access non-secret variables in your client-side code using `import.meta.env`:

```typescript theme={null}
// 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}`);
```

<Warning>
  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.
</Warning>

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

Access both secret and non-secret variables in your server code using `process.env`:

```typescript theme={null}
// 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

<Info>
  Remember: Non-secret variables are automatically available with the `VITE_` prefix for client-side
  access. You don't need to create separate variables.
</Info>

## Common Patterns

### API Configuration

```typescript theme={null}
// 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

```typescript theme={null}
// 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
```

<Note>
  Stardeck automatically provides `DATABASE_URL` for your app's managed database. Use
  `EXTERNAL_DATABASE_URL` or similar names for connecting to external databases.
</Note>

### Feature Flags

```typescript theme={null}
// 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.