Skip to main content

​
Environment Variables

Environment variables let you store configuration and secrets that your app needs, without hardcoding them into your source code.

​
When to Use Environment Variables

API Keys

Third-party service credentials

Configuration

Feature flags, URLs, settings

Secrets

Sensitive data that shouldn’t be in code

Environment-Specific

Different values for dev/staging/prod

​
Environment Variables by Backend Type

How you manage environment variables depends on which backend system you’re using.
Which backend am I using? If you see a “Database” button in the preview header, you’re on Liquid Backend. Otherwise, you’re using Supabase. See Backend Systems.

​
Liquid Backend (Specular)

With Liquid Backend, environment variables are split between frontend and backend:

​
Frontend Variables

For variables used in your React Native code:
1

Open Settings

Click More → Environment Variables in the project menu
2

Add Variable

Enter the variable name and value:
  • Name: GOOGLE_MAPS_API_KEY
  • Value: your_api_key_here
3

Save

Click Save to store the variable
Access in your code: 
import Constants from 'expo-constants';

const mapsKey = Constants.expoConfig?.extra?.GOOGLE_MAPS_API_KEY;

​
Backend Variables (Server-Side Secrets)

For secrets that should never be exposed to the frontend:
Secrets like OPENAI_API_KEY, STRIPE_SECRET_KEY, or database credentials should be stored in Specular, not as frontend environment variables.
Server-side secrets are configured through Specular:
  1. When you request features that need secrets (e.g., “Add AI chat using OpenAI”), the AI prompts you for the key
  2. Secrets are stored securely in Specular’s backend
  3. They’re never exposed to your frontend code
Example prompt: 
Add AI chat using GPT-4. Use my OpenAI API key for the backend.
The AI will configure the secret securely in Specular.

​
Supabase

With Supabase, the database connection is handled automatically via OAuth integration—no manual API key configuration required.

​
Supabase Connection

Supabase credentials are managed through OAuth:
1

Connect via OAuth

Click More → Supabase and authorize the connection
2

Automatic Configuration

The OAuth integration handles all authentication securely
You don’t need to manually add SUPABASE_URL or SUPABASE_ANON_KEY—the OAuth connection manages this for you.

​
Additional Environment Variables

For other environment variables (not Supabase credentials), use More → Environment Variables: 
import Constants from 'expo-constants';

// Access any environment variable
const mapsKey = Constants.expoConfig?.extra?.GOOGLE_MAPS_API_KEY;

​
Server-Side Secrets with Supabase

For Supabase, server-side secrets should be stored in Edge Functions:
  1. Create an Edge Function in Supabase Dashboard
  2. Add secrets via Supabase CLI: 
    supabase secrets set OPENAI_API_KEY=sk-...
  3. Access in your Edge Function: 
    const apiKey = Deno.env.get('OPENAI_API_KEY');

​
Using Environment Variables in Code

​
Accessing Variables

All frontend environment variables are accessed the same way: 
import Constants from 'expo-constants';

// Access any environment variable
const apiKey = Constants.expoConfig?.extra?.MY_API_KEY;
const baseUrl = Constants.expoConfig?.extra?.API_BASE_URL;

​
With Default Values

const apiUrl = Constants.expoConfig?.extra?.API_URL ?? 'https://api.example.com';

​
In AI Prompts

Tell the AI to use environment variables: 
Add weather data to the home screen. Use the OPENWEATHER_API_KEY
environment variable for the API key.

​
Common Environment Variables

​
For All Projects

VariablePurposeSafe for Frontend?
GOOGLE_MAPS_API_KEYGoogle Maps API✅ Yes (with restrictions)
SENTRY_DSNError tracking✅ Yes
POSTHOG_API_KEYAnalytics✅ Yes

​
For Liquid Backend Projects

VariableWhere StoredNotes
Frontend keysNatively Env VarsVia More → Environment Variables
Server secretsSpecularConfigured via AI prompts

​
For Supabase Projects

ItemHow It’s Handled
Supabase connectionAutomatic via OAuth
Additional frontend varsMore → Environment Variables
Server secretsSupabase Edge Function secrets

​
Best Practices

API keys, passwords, and tokens should always be in environment variables, not in your code.
Use clear names like STRIPE_PUBLIC_KEY instead of KEY1
Only public keys belong in frontend environment variables. Server-side secrets go in your backend.
Keep track of which environment variables your app needs for deployment.

​
Environment Differences

Environment variables can differ between development and production:
EnvironmentPurpose
DevelopmentTesting and building features
ProductionLive app used by real users
When you deploy, make sure production environment variables are set correctly.

​
Troubleshooting

  • Check the variable name matches exactly (case-sensitive)
  • Ensure you saved after adding the variable
  • Reload the preview after changes
  • Verify the key is correct (copy-paste from source)
  • Check if the key has proper permissions/scopes
  • Move server-side secrets to backend (Specular or Edge Functions)
  • Use frontend environment variables only for public keys
  • Check git history and rotate exposed secrets

Backend Systems

Understand Liquid Backend vs Supabase

Supabase Integration

Full Supabase setup guide