Skip to main content

Environment Variables

This guide covers all environment variables used in the Loyalteez platform, including what's required, optional, and deprecated.

Overview​

The Loyalteez platform uses environment variables to configure blockchain networks, API endpoints, authentication, and smart contracts. As of January 2025, we've streamlined the configuration to only 11 required variables for production deployment.

Required Variables (11 Total)​

Core Authentication (3 variables)​

# Privy Authentication (Required)
VITE_PRIVY_APP_ID=your_privy_app_id_here

# Supabase Database (Required)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISH_KEY=your_supabase_anon_key_here

Important: Always use VITE_SUPABASE_PUBLISH_KEY (the anon/publishable key) in frontend applications. Never use the service role key in browser code.

Blockchain Network (4 variables)​

# Soneium Mainnet (Production)
VITE_CHAIN_ID=1868
VITE_NETWORK_NAME=soneium
VITE_RPC_URL=https://rpc.soneium.org
VITE_BLOCK_EXPLORER=https://soneium.blockscout.com/

# OR Soneium Testnet (Development)
# VITE_CHAIN_ID=1946
# VITE_NETWORK_NAME=soneium-minato
# VITE_RPC_URL=https://rpc.minato.soneium.org/
# VITE_BLOCK_EXPLORER=https://explorer-testnet.soneium.org

Smart Contracts (4 variables)​

# Mainnet Contract Addresses (Deployed 2024)
VITE_LOYALTEEZ_ADDRESS=0x5242b6DB88A72752ac5a54cFe6A7DB8244d743c9
VITE_PERK_NFT_ADDRESS=0x8157728D20C0d092b84290C31D76ae0453300E95
VITE_POINTS_SALE_ADDRESS=0x5269B83F6A4E31bEdFDf5329DC052FBb661e3c72
VITE_USDC_ADDRESS=0xbA9986D2381edf1DA03B0B9c1f8b00dc4AacC369

Optional Variables​

These variables have sensible defaults and are not required:

API Worker URLs​

# Optional - Default values shown
VITE_API_URL=https://api.loyalteez.app
VITE_PREGENERATION_API=https://register.loyalteez.app
VITE_REWARD_PROCESSOR_API=https://reward.loyalteez.app
VITE_GAS_RELAYER_URL=https://relayer.loyalteez.app

Payment Processing​

# Optional - API handles all payment processing
VITE_PUB_KEY=pk_test_your_stripe_key
VITE_SINGLE_BUY=price_your_price_id
VITE_BASIC_SUB=price_your_subscription_price_id

Note: The Partner Frontend API handles payment processing. These variables are defined in code but not actively used in production.

Stage Detection​

# Optional - Auto-detected from hostname
VITE_STAGE=development  # or 'production'

Removed/Deprecated Variables​

The following variables were removed in January 2025 as they are no longer needed:

❌ WalletConnect​

# REMOVED: WalletConnect disabled in Privy configuration
# VITE_WALLET_CONNECT_PROJECT_ID=your_project_id

Why removed: WalletConnect is disabled in the Privy configuration, so this variable is not used.

❌ Treasury & Fees​

# REMOVED: Handled by smart contracts
# VITE_TREASURY_ADDRESS=0x...
# VITE_PLATFORM_FEE_BPS=250

Why removed: Treasury address and platform fees are hardcoded in the smart contracts and don't need to be configurable via environment variables.

❌ Alchemy Account Abstraction​

# REMOVED: Using Privy embedded wallets instead
# VITE_ALCHEMY_API_KEY=your_key
# VITE_ALCHEMY_POLICY_ID=your_policy_id

Why removed: We use Privy's embedded wallet infrastructure instead of Alchemy's account abstraction.

❌ Supabase Service Key​

# SECURITY RISK: Never use in browser
# VITE_SUPABASE_SERVICE_KEY=sb_secret_...

Why removed: The service role key bypasses Row Level Security (RLS) and should never be used in frontend code. Always use VITE_SUPABASE_PUBLISH_KEY instead.

Environment Files​

.env.example Template​

Create a .env.example file in your project root:

# =============================================================================
# LOYALTEEZ ENVIRONMENT VARIABLES
# =============================================================================
# Copy this file to .env and fill in your actual values
# =============================================================================

# CORE AUTHENTICATION (REQUIRED)
VITE_PRIVY_APP_ID=your_privy_app_id_here
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISH_KEY=your_supabase_anon_key_here

# BLOCKCHAIN NETWORK (REQUIRED)
VITE_CHAIN_ID=1868
VITE_NETWORK_NAME=soneium
VITE_RPC_URL=https://rpc.soneium.org
VITE_BLOCK_EXPLORER=https://soneium.blockscout.com/

# SMART CONTRACTS (REQUIRED)
VITE_LOYALTEEZ_ADDRESS=0x5242b6DB88A72752ac5a54cFe6A7DB8244d743c9
VITE_PERK_NFT_ADDRESS=0x8157728D20C0d092b84290C31D76ae0453300E95
VITE_POINTS_SALE_ADDRESS=0x5269B83F6A4E31bEdFDf5329DC052FBb661e3c72
VITE_USDC_ADDRESS=0xbA9986D2381edf1DA03B0B9c1f8b00dc4AacC369

# OPTIONAL VARIABLES
# VITE_API_URL=https://api.loyalteez.app
# VITE_PREGENERATION_API=https://register.loyalteez.app
# VITE_GAS_RELAYER_URL=https://relayer.loyalteez.app

.env (Your Local Configuration)​

# Copy .env.example to .env
cp .env.example .env

# Fill in your actual values
# NEVER commit .env to version control

Add to your .gitignore:

.env
.env.local
.env.*.local

Configuration Validation​

The platform includes built-in configuration validation in src/utils/configValidator.ts:

import { validateConfig } from './utils/configValidator';

// Validate on app startup
const result = validateConfig();
if (!result.valid) {
  console.error('Configuration errors:', result.errors);
  console.error('Missing variables:', result.missing);
}

Validation Error UI​

If required variables are missing, the app displays a helpful configuration error screen:

Configuration Error
Missing 2 required environment variable(s).

Missing Required Variables:
- VITE_PRIVY_APP_ID: Privy App ID for authentication
- VITE_SUPABASE_URL: Supabase project URL

Quick Fix:
1. Copy .env.example to .env
2. Fill in all required variables with your actual values
3. Restart the development server

TypeScript Definitions​

Environment variables are strongly typed in src/vite-env.d.ts:

interface ImportMetaEnv {
  // Core
  readonly VITE_PRIVY_APP_ID: string;
  readonly VITE_SUPABASE_URL: string;
  readonly VITE_SUPABASE_PUBLISH_KEY: string;
  
  // Blockchain
  readonly VITE_CHAIN_ID: string;
  readonly VITE_NETWORK_NAME: string;
  readonly VITE_RPC_URL: string;
  readonly VITE_BLOCK_EXPLORER: string;
  
  // Contracts
  readonly VITE_LOYALTEEZ_ADDRESS: string;
  readonly VITE_PERK_NFT_ADDRESS: string;
  readonly VITE_POINTS_SALE_ADDRESS: string;
  readonly VITE_USDC_ADDRESS: string;
  
  // Optional
  readonly VITE_API_URL?: string;
  readonly VITE_PREGENERATION_API?: string;
  readonly VITE_GAS_RELAYER_URL?: string;
}

Best Practices​

1. Never Commit Secrets​

# ✅ Good
.env
.env.local

# ❌ Bad
.env.production  # Contains production secrets

2. Use Publishable Keys in Frontend​

# ✅ Good - Browser-safe, respects RLS
VITE_SUPABASE_PUBLISH_KEY=eyJhbGci...

# ❌ Bad - Bypasses security, never use in browser
VITE_SUPABASE_SERVICE_KEY=eyJhbGci...

3. Document Required Variables​

Always include an .env.example file with:

  • All required variables (empty values)
  • Comments explaining what each variable does
  • Examples or placeholder values

4. Validate Early​

// Validate config before rendering app
const config = validateConfig();
if (!config.valid) {
  return <ConfigurationErrorScreen errors={config.errors} />;
}

5. Use Environment-Specific Files​

# Development
.env.development

# Staging
.env.staging

# Production
.env.production

Troubleshooting​

"Missing 2 required environment variable(s)"​

Solution: You're missing VITE_SINGLE_BUY and VITE_BASIC_SUB. As of January 2025, these are optional. Update your configValidator.ts:

{
  key: 'VITE_SINGLE_BUY',
  required: false,  // Changed from true
  // ...
}

"Supabase connection failed"​

Cause: Using wrong Supabase key or incorrect URL.

Solution:

  1. Verify VITE_SUPABASE_URL is correct
  2. Use VITE_SUPABASE_PUBLISH_KEY (anon key), not service key
  3. Check key in Supabase dashboard → Settings → API

"Network not supported"​

Cause: Chain ID mismatch or RPC URL incorrect.

Solution:

  1. Verify VITE_CHAIN_ID=1868 for mainnet
  2. Check VITE_RPC_URL is accessible
  3. Test RPC: curl https://rpc.soneium.org

Migration Guide​

From Old Configuration (Pre-Jan 2025)​

If you have an old .env file, update it:

# 1. Remove deprecated variables
# Delete: VITE_WALLET_CONNECT_PROJECT_ID
# Delete: VITE_TREASURY_ADDRESS
# Delete: VITE_PLATFORM_FEE_BPS
# Delete: VITE_ALCHEMY_API_KEY
# Delete: VITE_ALCHEMY_POLICY_ID
# Delete: VITE_SUPABASE_SERVICE_KEY

# 2. Make Stripe variables optional (or remove if not used)
# VITE_SINGLE_BUY can be removed
# VITE_BASIC_SUB can be removed

# 3. Keep only the 11 required variables
# (See "Required Variables" section above)

Changelog​

January 2025​

  • ✅ Reduced required variables from 13+ to 11
  • ✅ Made Stripe variables optional (API handles payments)
  • ❌ Removed WalletConnect configuration (disabled)
  • ❌ Removed Treasury/Fee variables (hardcoded in contracts)
  • ❌ Removed Alchemy AA variables (using Privy)
  • ❌ Removed Supabase service key (security risk)
  • ✅ Added optional worker URL variables with defaults

December 2024​

  • Initial environment variable documentation
Last updated on