Environment Variables

Configure environment variables to manage API keys, endpoints, and environment-specific settings.

Understanding Environment Variables

The starter uses EXPO_PUBLIC_ prefixed environment variables that are:

Validated with Zod schemas
Available at build time and runtime
Environment-specific (development, preview, production)

Environment Variable Schema

All environment variables are defined in packages/config/src/env.ts:

const envSchema = z.object({
  EXPO_PUBLIC_API_URL: z.string().url().default('https://api.example.com'),
  EXPO_PUBLIC_APP_ENV: z
    .enum(['development', 'preview', 'production'])
    .default('development'),
  EXPO_PUBLIC_FIREBASE_API_KEY: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_PROJECT_ID: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_APP_ID: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_EMAIL_CONTINUE_URL: z.string().optional(),
  EXPO_PUBLIC_FIREBASE_AUTH_LINK_DOMAIN: z.string().optional(),
  EXPO_PUBLIC_REVENUECAT_API_KEY: z.string().optional(),
  EXPO_PUBLIC_REVENUECAT_IOS_API_KEY: z.string().optional(),
  EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY: z.string().optional(),
  EXPO_PUBLIC_SENTRY_DSN: z.string().optional(),
  EXPO_PUBLIC_ANALYTICS_ENABLED: z
    .string()
    .transform((val) => val === 'true')
    .default('true'),
  EXPO_PUBLIC_DEBUG_MODE: z
    .string()
    .transform((val) => val === 'true')
    .default('false'),
});

Local Development Setup

1. Create .env File

Create a .env file in the repository root:

# DO NOT COMMIT THIS FILE
# Add .env to .gitignore

# Environment
EXPO_PUBLIC_APP_ENV=development

# API Configuration
EXPO_PUBLIC_API_URL=http://localhost:3000

# Firebase Configuration (if using Firebase adapter)
EXPO_PUBLIC_FIREBASE_API_KEY=your-api-key
EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
EXPO_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
EXPO_PUBLIC_FIREBASE_APP_ID=your-app-id
EXPO_PUBLIC_FIREBASE_EMAIL_CONTINUE_URL=https://amisi-mobile-starter.web.app/verify-email
EXPO_PUBLIC_FIREBASE_AUTH_LINK_DOMAIN=amisi-mobile-starter.web.app

# RevenueCat Configuration (if using RevenueCat adapter)
EXPO_PUBLIC_REVENUECAT_API_KEY=your-universal-key
# OR platform-specific keys:
# EXPO_PUBLIC_REVENUECAT_IOS_API_KEY=your-ios-key
# EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY=your-android-key

# Optional: Sentry
EXPO_PUBLIC_SENTRY_DSN=your-sentry-dsn

# Feature Toggles
EXPO_PUBLIC_ANALYTICS_ENABLED=true
EXPO_PUBLIC_DEBUG_MODE=true

2. Add to .gitignore

Ensure .env is in .gitignore:

# Environment variables
.env
.env.local
.env.*.local

3. Restart Development Server

After creating or modifying .env:

bun run start:clear

Environment-Specific Configuration

Development Environment

For local development:

EXPO_PUBLIC_APP_ENV=development
EXPO_PUBLIC_API_URL=http://localhost:3000
EXPO_PUBLIC_DEBUG_MODE=true

Preview Environment

For testing builds:

EXPO_PUBLIC_APP_ENV=preview
EXPO_PUBLIC_API_URL=https://preview-api.example.com
EXPO_PUBLIC_DEBUG_MODE=true
EXPO_PUBLIC_ANALYTICS_ENABLED=true

Production Environment

For production builds:

EXPO_PUBLIC_APP_ENV=production
EXPO_PUBLIC_API_URL=https://api.example.com
EXPO_PUBLIC_DEBUG_MODE=false
EXPO_PUBLIC_ANALYTICS_ENABLED=true

EAS Secrets (Recommended for Production)

For EAS builds, use EAS Secrets instead of committing sensitive values.

Create Secrets

# Firebase secrets
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_API_KEY --value "your-key"
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN --value "your-domain"
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_PROJECT_ID --value "your-id"
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET --value "your-bucket"
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID --value "your-sender-id"
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_APP_ID --value "your-app-id"

# RevenueCat secrets
eas secret:create --scope project --name EXPO_PUBLIC_REVENUECAT_API_KEY --value "your-key"

# API URL (environment-specific)
eas secret:create --scope project --name EXPO_PUBLIC_API_URL --value "https://api.example.com"

List Secrets

eas secret:list

Delete Secrets

eas secret:delete --name EXPO_PUBLIC_FIREBASE_API_KEY

Build Profile Environment Variables

You can also set environment variables in eas.json for each build profile:

{
  "build": {
    "production": {
      "env": {
        "APP_ENV": "production",
        "EXPO_PUBLIC_API_URL": "https://api.example.com"
      }
    },
    "preview": {
      "env": {
        "APP_ENV": "preview",
        "EXPO_PUBLIC_API_URL": "https://preview-api.example.com"
      }
    },
    "development": {
      "env": {
        "APP_ENV": "development"
      }
    }
  }
}

Note: EAS Secrets take precedence over eas.json env values.

Accessing Environment Variables

In Code

Import from @amisi/config:

import { env, getApiUrl, isDevelopment } from '@amisi/config';

// Direct access
const apiUrl = env.EXPO_PUBLIC_API_URL;
const firebaseKey = env.EXPO_PUBLIC_FIREBASE_API_KEY;

// Helper functions
const url = getApiUrl();
const isDev = isDevelopment();

Available Helpers

// Environment checks
isDevelopment(): boolean
isPreview(): boolean
isProduction(): boolean

// Configuration getters
getApiUrl(): string
isDebugMode(): boolean
isAnalyticsEnabled(): boolean

Required Variables by Adapter

Firebase Adapter

Required when using auth.adapter: "firebase":

EXPO_PUBLIC_FIREBASE_API_KEY=required
EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=required
EXPO_PUBLIC_FIREBASE_PROJECT_ID=required
EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=required
EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=required
EXPO_PUBLIC_FIREBASE_APP_ID=required
EXPO_PUBLIC_FIREBASE_EMAIL_CONTINUE_URL=recommended for verify email deep links
EXPO_PUBLIC_FIREBASE_AUTH_LINK_DOMAIN=recommended for firebase auth link domain

RevenueCat Adapter

Required when using subscriptions.adapter: "revenuecat":

# Option 1: Universal key
EXPO_PUBLIC_REVENUECAT_API_KEY=required

# Option 2: Platform-specific keys
EXPO_PUBLIC_REVENUECAT_IOS_API_KEY=required
EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY=required

Mock Adapters

No environment variables required when using mock adapters.

Validation

Environment variables are validated on app startup using Zod schemas.

Validation Errors

If validation fails, you’ll see detailed error messages:

❌ Invalid environment variables:
  - EXPO_PUBLIC_API_URL: Invalid url
  - EXPO_PUBLIC_FIREBASE_API_KEY: Required

Adding New Variables

To add a new environment variable:

Update schema in packages/config/src/env.ts:

const envSchema = z.object({
  // ... existing variables
  EXPO_PUBLIC_MY_NEW_VAR: z.string().optional(),
});

Update TypeScript types (automatic from Zod):

export type Env = z.infer<typeof envSchema>;

Add to .env:

EXPO_PUBLIC_MY_NEW_VAR=my-value

Access in code:

import { env } from '@amisi/config';
const myVar = env.EXPO_PUBLIC_MY_NEW_VAR;

Security Best Practices

1. Never Commit Secrets

Add .env to .gitignore
Use EAS Secrets for sensitive values
Use .env.example for documentation

2. Use EAS Secrets for Production

# Good: Use EAS Secrets
eas secret:create --scope project --name EXPO_PUBLIC_FIREBASE_API_KEY --value "key"

# Bad: Hardcode in eas.json
{
  "env": {
    "EXPO_PUBLIC_FIREBASE_API_KEY": "hardcoded-key"
  }
}

3. Restrict API Keys

Use Firebase API key restrictions
Use RevenueCat environment-specific keys
Rotate keys regularly

4. Environment Separation

Use different Firebase projects for dev/prod
Use different RevenueCat projects for dev/prod
Never use production keys in development

Example .env.example

Create .env.example for documentation:

# Environment Configuration Example
# Copy this file to .env and fill in your values

# Environment
EXPO_PUBLIC_APP_ENV=development

# API Configuration
EXPO_PUBLIC_API_URL=http://localhost:3000

# Firebase Configuration (optional - only if using Firebase adapter)
EXPO_PUBLIC_FIREBASE_API_KEY=
EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=
EXPO_PUBLIC_FIREBASE_PROJECT_ID=
EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=
EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
EXPO_PUBLIC_FIREBASE_APP_ID=
EXPO_PUBLIC_FIREBASE_EMAIL_CONTINUE_URL=https://amisi-mobile-starter.web.app/verify-email
EXPO_PUBLIC_FIREBASE_AUTH_LINK_DOMAIN=amisi-mobile-starter.web.app

# RevenueCat Configuration (optional - only if using RevenueCat adapter)
EXPO_PUBLIC_REVENUECAT_API_KEY=

# Feature Toggles
EXPO_PUBLIC_ANALYTICS_ENABLED=true
EXPO_PUBLIC_DEBUG_MODE=true

Troubleshooting

Variables Not Loading

Solution: Restart the development server:

bun run start:clear

Validation Errors

Solution: Check that all required variables are set and match the schema format.

EAS Build Missing Variables

Solution: Ensure variables are either:

Set as EAS Secrets, OR
Defined in eas.json env block

Variables Undefined at Runtime

Solution: Ensure variables have EXPO_PUBLIC_ prefix for client-side access.

Environment Variables

Environment Variables

Understanding Environment Variables

Environment Variable Schema

Local Development Setup

1. Create .env File

2. Add to .gitignore

3. Restart Development Server

Environment-Specific Configuration

Development Environment

Preview Environment

Production Environment

EAS Secrets (Recommended for Production)

Create Secrets

List Secrets

Delete Secrets

Build Profile Environment Variables

Accessing Environment Variables

In Code

Available Helpers

Required Variables by Adapter

Firebase Adapter

RevenueCat Adapter

Mock Adapters

Validation

Validation Errors

Adding New Variables

Security Best Practices

1. Never Commit Secrets

2. Use EAS Secrets for Production

3. Restrict API Keys

4. Environment Separation

Example .env.example

Troubleshooting

Variables Not Loading

Validation Errors

EAS Build Missing Variables

Variables Undefined at Runtime

Official Documentation

Next Steps

​Environment Variables

​Understanding Environment Variables

​Environment Variable Schema

​Local Development Setup

​1. Create .env File

​2. Add to .gitignore

​3. Restart Development Server

​Environment-Specific Configuration

​Development Environment

​Preview Environment

​Production Environment

​EAS Secrets (Recommended for Production)

​Create Secrets

​List Secrets

​Delete Secrets

​Build Profile Environment Variables

​Accessing Environment Variables

​In Code

​Available Helpers

​Required Variables by Adapter

​Firebase Adapter

​RevenueCat Adapter

​Mock Adapters

​Validation

​Validation Errors

​Adding New Variables

​Security Best Practices

​1. Never Commit Secrets

​2. Use EAS Secrets for Production

​3. Restrict API Keys

​4. Environment Separation

​Example .env.example

​Troubleshooting

​Variables Not Loading

​Validation Errors

​EAS Build Missing Variables

​Variables Undefined at Runtime

​Official Documentation

​Next Steps

Environment Variables

Understanding Environment Variables

Environment Variable Schema

Local Development Setup

1. Create .env File

2. Add to .gitignore

3. Restart Development Server

Environment-Specific Configuration

Development Environment

Preview Environment

Production Environment

EAS Secrets (Recommended for Production)

Create Secrets

List Secrets

Delete Secrets

Build Profile Environment Variables

Accessing Environment Variables

In Code

Available Helpers

Required Variables by Adapter

Firebase Adapter

RevenueCat Adapter

Mock Adapters

Validation

Validation Errors

Adding New Variables

Security Best Practices

1. Never Commit Secrets

2. Use EAS Secrets for Production

3. Restrict API Keys

4. Environment Separation

Example .env.example

Troubleshooting

Variables Not Loading

Validation Errors

EAS Build Missing Variables

Variables Undefined at Runtime

Official Documentation

Next Steps