Flowless

Appearance

Environment Variables ​

Complete guide to configuring environment variables for Flowless integration in your frontend and backend applications.

Overview ​

Environment variables are used to configure your application's connection to Flowless and manage sensitive credentials securely.

DANGER

Never commit environment variables to version control! Always use .env files and add them to .gitignore.

Frontend Environment Variables ​

React (Vite) ​

Create .env file in your React project root:

bash
# Flowless instance URL
VITE_FLOWLESS_URL=https://your-instance-name.pubflow.com

# Optional: API base URL (your backend)
VITE_API_URL=https://api.yourdomain.com

# Optional: Environment
VITE_ENV=production

Usage in code:

typescript
const FLOWLESS_URL = import.meta.env.VITE_FLOWLESS_URL;
const API_URL = import.meta.env.VITE_API_URL;

Next.js ​

Create .env.local file in your Next.js project root:

bash
# Flowless instance URL (public)
NEXT_PUBLIC_FLOWLESS_URL=https://your-instance-name.pubflow.com

# API URL (public)
NEXT_PUBLIC_API_URL=https://api.yourdomain.com

# Server-side only (not exposed to browser)
FLOWLESS_URL=https://your-instance-name.pubflow.com
BRIDGE_SECRET=bridge_secret_abc123xyz789

Usage in code:

typescript
// Client-side
const FLOWLESS_URL = process.env.NEXT_PUBLIC_FLOWLESS_URL;

// Server-side only
const BRIDGE_SECRET = process.env.BRIDGE_SECRET;

React Native (Expo) ​

Create .env file in your Expo project root:

bash
# Flowless instance URL
EXPO_PUBLIC_FLOWLESS_URL=https://your-instance-name.pubflow.com

# API URL
EXPO_PUBLIC_API_URL=https://api.yourdomain.com

# Optional: Log mode
EXPO_PUBLIC_LOG_MODE=production

Usage in code:

typescript
const FLOWLESS_URL = process.env.EXPO_PUBLIC_FLOWLESS_URL;
const API_URL = process.env.EXPO_PUBLIC_API_URL;

Backend Environment Variables ​

Node.js / Express / Hono ​

Create .env file in your backend project root:

bash
# ============================================
# FLOWLESS CONFIGURATION
# ============================================

# Flowless instance URL
FLOWLESS_URL=https://your-instance-name.pubflow.com

# Bridge Secret (KEEP SECURE!)
BRIDGE_SECRET=bridge_secret_abc123xyz789

# Validation mode (STANDARD, ADVANCED, STRICT)
VALIDATION_MODE=STANDARD

# ============================================
# APPLICATION CONFIGURATION
# ============================================

# Server port
PORT=3000

# Environment
NODE_ENV=production

# API URL
API_URL=https://api.yourdomain.com

# Frontend URL (for CORS)
FRONTEND_URL=https://yourdomain.com

# ============================================
# DATABASE CONFIGURATION
# ============================================

# Database URL
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

# ============================================
# CACHE CONFIGURATION
# ============================================

# Redis URL (optional)
REDIS_URL=redis://localhost:6379

# Trust token cache TTL (seconds)
TRUST_TOKEN_CACHE_TTL=300

# ============================================
# LOGGING
# ============================================

# Log level (DEBUG, INFO, WARN, ERROR)
LOG_LEVEL=INFO

# Log mode (development, production)
LOG_MODE=production

Usage in code:

typescript
const FLOWLESS_URL = process.env.FLOWLESS_URL!;
const BRIDGE_SECRET = process.env.BRIDGE_SECRET!;
const VALIDATION_MODE = process.env.VALIDATION_MODE || 'STANDARD';

Environment-Specific Configuration ​

Development ​

.env.development

bash
FLOWLESS_URL=https://dev-instance.pubflow.com
BRIDGE_SECRET=dev_bridge_secret_123
VALIDATION_MODE=STANDARD
NODE_ENV=development
LOG_LEVEL=DEBUG

Staging ​

.env.staging

bash
FLOWLESS_URL=https://staging-instance.pubflow.com
BRIDGE_SECRET=staging_bridge_secret_456
VALIDATION_MODE=ADVANCED
NODE_ENV=staging
LOG_LEVEL=INFO

Production ​

.env.production

bash
FLOWLESS_URL=https://prod-instance.pubflow.com
BRIDGE_SECRET=prod_bridge_secret_789
VALIDATION_MODE=STRICT
NODE_ENV=production
LOG_LEVEL=WARN

Security Best Practices ​

1. Never Commit Secrets ​

Add to .gitignore:

# Environment variables
.env
.env.local
.env.development
.env.staging
.env.production
.env.*.local

2. Use Different Secrets per Environment ​

bash
# ❌ Bad - same secret everywhere
BRIDGE_SECRET=bridge_secret_123

# ✅ Good - different secrets
# Dev:     dev_bridge_secret_abc
# Staging: staging_bridge_secret_def
# Prod:    prod_bridge_secret_xyz

3. Rotate Secrets Regularly ​

bash
# Rotate every 90 days
# Old: bridge_secret_abc123
# New: bridge_secret_xyz789

4. Validate Required Variables ​

typescript
function validateEnv() {
  const required = [
    'FLOWLESS_URL',
    'BRIDGE_SECRET',
    'DATABASE_URL',
  ];

  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
  }
}

validateEnv();

Loading Environment Variables ​

Node.js (dotenv) ​

bash
npm install dotenv
typescript
import 'dotenv/config';

// Or
import dotenv from 'dotenv';
dotenv.config();

Bun ​

typescript
// Bun loads .env automatically
const FLOWLESS_URL = process.env.FLOWLESS_URL;

Docker ​

yaml
# docker-compose.yml
version: '3.8'
services:
  api:
    build: .
    env_file:
      - .env.production
    environment:
      - FLOWLESS_URL=${FLOWLESS_URL}
      - BRIDGE_SECRET=${BRIDGE_SECRET}

Complete Example ​

Frontend (.env) ​

bash
VITE_FLOWLESS_URL=https://my-app.pubflow.com
VITE_API_URL=https://api.myapp.com

Backend (.env) ​

bash
# Flowless
FLOWLESS_URL=https://my-app.pubflow.com
BRIDGE_SECRET=bridge_secret_abc123xyz789
VALIDATION_MODE=STANDARD

# Server
PORT=3000
NODE_ENV=production

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp

# Cache
REDIS_URL=redis://localhost:6379
TRUST_TOKEN_CACHE_TTL=300

# Logging
LOG_LEVEL=INFO

Troubleshooting ​

"Environment variable not found" ​

typescript
// ❌ Wrong
const url = process.env.FLOWLESS_URL;

// ✅ Correct - with fallback
const url = process.env.FLOWLESS_URL || 'https://default.pubflow.com';

// ✅ Better - throw error if missing
const url = process.env.FLOWLESS_URL;
if (!url) throw new Error('FLOWLESS_URL not set');

"Variables not loading" ​

  1. Check .env file exists
  2. Check .env is in project root
  3. Check dotenv is imported before usage
  4. Restart development server

Next Steps ​