# Environment Variables

Configure the Account UI by setting environment variables in your `.env` file or deployment platform.

## Quick Setup — Single Variable

For the common "unified deployment" where API, Account, and CMS all live on the same Quickback origin, you only need **one** variable:

```bash
# Points at the Quickback Worker origin
VITE_QUICKBACK_URL=https://secure.example.com
```

When `VITE_QUICKBACK_URL` is set, it's used as a fallback for the individual URL vars:

| Individual var | Used first | Falls back to |
|---|---|---|
| `VITE_QUICKBACK_API_URL` | if set | `${VITE_QUICKBACK_URL}` |
| `VITE_QUICKBACK_ACCOUNT_URL` | if set | `${VITE_QUICKBACK_URL}/account` |
| `VITE_QUICKBACK_CMS_URL` | if set | `${VITE_QUICKBACK_URL}/cms` |

> **VITE_QUICKBACK_APP_URL is independent**
>
> `VITE_QUICKBACK_APP_URL` points at the tenant's own frontend (where users are redirected after login). It's **not** derived from `VITE_QUICKBACK_URL` — set it separately if needed.


## Required Variables

At minimum, you need one of:

- **`VITE_QUICKBACK_URL`** — catch-all for the Quickback origin (recommended), **or**
- **`VITE_QUICKBACK_API_URL`** — explicit API URL (use this if your API lives on a different subdomain from Account/CMS)

### Split-subdomain setup

If your API, Account, and CMS live on separate custom subdomains, set them explicitly:

```bash
# Quickback API URL
VITE_QUICKBACK_API_URL=https://api.example.com

# Account UI URL (where the Account UI is deployed)
VITE_ACCOUNT_APP_URL=https://account.example.com

# Optional: override Account/CMS URLs for cross-origin links
VITE_QUICKBACK_ACCOUNT_URL=https://auth.example.com
VITE_QUICKBACK_CMS_URL=https://cms.example.com
```

> **Required Configuration**
>
> The application will throw an error if neither `VITE_QUICKBACK_URL` nor `VITE_QUICKBACK_API_URL` is set.


## App Identity

Configure your application's basic information:

```bash
# App name (displayed in UI)
VITE_APP_NAME=My Application

# Tagline (shown on landing pages)
VITE_APP_TAGLINE=Build faster, ship sooner

# Full description
VITE_APP_DESCRIPTION=A complete platform for building modern web applications

# Company information
VITE_COMPANY_NAME=My Company Inc.
VITE_COMPANY_ADDRESS=123 Main St, Suite 100, San Francisco, CA 94105
```

## URLs

### Main Application

```bash
# Your main application URL
# Users will be redirected here after authentication
VITE_QUICKBACK_APP_URL=https://app.example.com

# Organization/Tenant URL pattern (optional)
# Use {slug} as placeholder for organization identifier
# Examples:
#   /organizations/{slug}           -> app.example.com/organizations/acme
#   /workspace/{slug}               -> app.example.com/workspace/acme
#   https://{slug}.example.com      -> acme.example.com
VITE_TENANT_URL_PATTERN=/organizations/{slug}
```

### Support and Legal

```bash
# Support/help URL
VITE_SUPPORT_URL=https://support.example.com

# Privacy policy URL
VITE_PRIVACY_URL=https://example.com/privacy

# Terms of service URL
VITE_TERMS_URL=https://example.com/terms
```

## Email Configuration

```bash
# From address for all emails
VITE_EMAIL_FROM=noreply@example.com

# Reply-to address
VITE_EMAIL_REPLY_TO=support@example.com

# Support email address
VITE_SUPPORT_EMAIL=support@example.com

# AWS Region for SES (if using AWS SES)
VITE_EMAIL_REGION=us-east-1
```

## Branding

```bash
# Primary theme color (hex code)
VITE_THEME_COLOR=#1e293b

# SEO keywords (comma-separated)
VITE_SEO_KEYWORDS=saas,authentication,account management
```

## Feature Flags

Enable or disable features using boolean environment variables:

### Authentication Features

```bash
# Enable user signup (default: true)
ENABLE_SIGNUP=true

# Enable email verification after signup (default: true)
ENABLE_EMAIL_VERIFICATION=true

# Disable email deliverability checks (default: false)
# Set to true to skip checking if email addresses are deliverable
DISABLE_EMAIL_STATUS_CHECK=false

# Enable passkey (WebAuthn) login (default: true)
ENABLE_PASSKEY=true

# Enable email OTP login and signup (default: true)
ENABLE_EMAIL_OTP=true

# Enable email+password login and signup (default: false)
ENABLE_PASSWORD=false
```

### Account Management Features

```bash
# Enable file uploads (avatar, etc.) (default: false)
VITE_ENABLE_FILE_UPLOADS=false
```

### Organization Features

```bash
# Enable multi-tenant organizations (default: true)
ENABLE_ORGANIZATIONS=true

# Enable Teams (sub-groups within an organization) (default: false)
# Auto-set to true when the BA config has organization({ teams: { enabled: true } }).
# When false the Teams tab is hidden and the auth client doesn't expose team APIs.
VITE_ENABLE_ORG_TEAMS=false
```

### Admin Features

```bash
# Enable admin panel (default: true)
ENABLE_ADMIN=true
```

## Complete Example

Here's a complete `.env` file with all common configuration:

```bash title=".env"
# ===== REQUIRED =====
VITE_QUICKBACK_API_URL=https://api.example.com
VITE_ACCOUNT_APP_URL=https://account.example.com

# ===== APP IDENTITY =====
VITE_APP_NAME=Acme SaaS
VITE_APP_TAGLINE=Build faster, ship sooner
VITE_APP_DESCRIPTION=The complete platform for modern web applications
VITE_COMPANY_NAME=Acme Corporation
VITE_COMPANY_ADDRESS=123 Main St, Suite 100, San Francisco, CA 94105

# ===== URLS =====
VITE_QUICKBACK_APP_URL=https://app.acme.com
VITE_TENANT_URL_PATTERN=/organizations/{slug}
VITE_SUPPORT_URL=https://help.acme.com
VITE_PRIVACY_URL=https://acme.com/privacy
VITE_TERMS_URL=https://acme.com/terms

# ===== EMAIL =====
VITE_EMAIL_FROM=noreply@acme.com
VITE_EMAIL_REPLY_TO=support@acme.com
VITE_SUPPORT_EMAIL=support@acme.com
VITE_EMAIL_REGION=us-east-1

# ===== BRANDING =====
VITE_THEME_COLOR=#3b82f6

# ===== SEO =====
VITE_SEO_KEYWORDS=saas,project management,team collaboration

# ===== FEATURES =====
ENABLE_SIGNUP=true
ENABLE_EMAIL_VERIFICATION=true
ENABLE_PASSKEY=true
ENABLE_EMAIL_OTP=true
ENABLE_PASSWORD=false
ENABLE_ORGANIZATIONS=true
VITE_ENABLE_ORG_TEAMS=true
ENABLE_ADMIN=true
VITE_ENABLE_FILE_UPLOADS=true
DISABLE_EMAIL_STATUS_CHECK=false
```

## Environment-Specific Configuration

### Development

```bash title=".env.development"
VITE_QUICKBACK_API_URL=http://localhost:8787
VITE_ACCOUNT_APP_URL=http://localhost:5173
VITE_QUICKBACK_APP_URL=http://localhost:3000
DISABLE_EMAIL_STATUS_CHECK=true
```

### Staging

```bash title=".env.staging"
VITE_QUICKBACK_API_URL=https://api-staging.example.com
VITE_ACCOUNT_APP_URL=https://account-staging.example.com
VITE_QUICKBACK_APP_URL=https://app-staging.example.com
```

### Production

```bash title=".env.production"
VITE_QUICKBACK_API_URL=https://api.example.com
VITE_ACCOUNT_APP_URL=https://account.example.com
VITE_QUICKBACK_APP_URL=https://app.example.com
DISABLE_EMAIL_STATUS_CHECK=false
```

## Cloudflare Pages Setup

When deploying to Cloudflare Pages, set environment variables in the dashboard:

1. Go to **Settings** → **Environment Variables**
2. Add each `VITE_*` variable
3. Separate values for **Production** and **Preview** branches

> **Build Variables**
>
> Vite environment variables are baked into the build at **build time**, not runtime. Changing a variable requires a rebuild and redeploy.


## Wrangler Configuration

For `wrangler dev` and `wrangler deploy`, add variables to `wrangler.toml`:

```toml title="wrangler.toml"
[env.production.vars]
VITE_QUICKBACK_API_URL = "https://api.example.com"
VITE_ACCOUNT_APP_URL = "https://account.example.com"
VITE_APP_NAME = "My App"
# ... other variables
```

Or use `.dev.vars` for local development (git-ignored):

```bash title=".dev.vars"
VITE_QUICKBACK_API_URL=http://localhost:8787
VITE_ACCOUNT_APP_URL=http://localhost:5173
```

## Runtime Configuration

Some values can be overridden at runtime using the config API:

```ts
import { setAppConfig } from '@/config/app';

setAppConfig({
  name: 'My Custom App',
  branding: {
    primaryColor: '#ff6600',
    logoUrl: '/custom-logo.png',
  },
  urls: {
    base: 'https://account.custom.com',
    app: 'https://app.custom.com',
  },
});
```

> **Limitations**
>
> Runtime configuration only works for values consumed by the React application. Environment variables used during the Vite build process cannot be changed at runtime.


## Validation

The Account UI validates configuration on startup:

- **Missing VITE_QUICKBACK_API_URL**: Throws error
- **Invalid URLs**: Logs warning
- **Missing optional fields**: Uses defaults

Check the browser console for configuration warnings.

## Next Steps

- **[Feature Flags](/stack/account-ui/features)** - Detailed feature configuration
- **[Customization](/stack/account-ui/customization)** - Customize labels and messages
- **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds and bundles Account UI
