Backend Environment Switching

This document explains how to switch between localhost and Vercel backends during development.

Overview

The frontend supports connecting to multiple backends:

Localhost: Backend running locally on http://localhost:8000 (for development)
Vercel: Production backend at https://plings-backend.vercel.app (for testing)
Custom IP: Backend running on any custom IP address (for remote development)

Environment Configuration

Environment Variables

Variable	Description	Example
`VITE_GRAPHQL_ENDPOINT`	GraphQL endpoint URL	`http://localhost:8000/graphql/`
`VITE_BACKEND_URL`	Backend base URL	`http://localhost:8000`
`VITE_BACKEND_ENV`	Environment identifier	`localhost` or `vercel`

Environment Files

.env.example - Template file with example configuration
.env.localhost - Localhost backend configuration
.env.vercel - Vercel backend configuration
.env.local - Active configuration (automatically managed)

Switching Methods

Method 1: NPM Scripts (Recommended)

# Switch to localhost backend and start dev server
npm run dev:local

# Switch to Vercel backend and start dev server
npm run dev:vercel

# Switch backend without starting server
npm run backend:local
npm run backend:vercel

Method 2: Manual Environment File Copy

# Switch to localhost
cp .env.localhost .env.local

# Switch to Vercel
cp .env.vercel .env.local

Method 3: Development UI Switcher

In development mode, a “Backend” button appears:

Desktop: Bottom-right corner
Mobile: Bottom-center for better accessibility

Click the “Backend” button to open the switcher panel
View current backend configuration and connection status
Switch between localhost/Vercel/Custom backends
For custom backend:
- Enter IP address with port (e.g., 192.168.1.100:8000)
- Click “Apply” to save and switch
- The IP is saved in localStorage for persistence
Test connection to verify backend availability
Follow CLI instructions to complete the switch

Backend Configuration Details

Localhost Backend

VITE_GRAPHQL_ENDPOINT=http://localhost:8000/graphql/
VITE_BACKEND_URL=http://localhost:8000
VITE_BACKEND_ENV=localhost

Vercel Backend

VITE_GRAPHQL_ENDPOINT=https://plings-backend.vercel.app/graphql/
VITE_BACKEND_URL=https://plings-backend.vercel.app
VITE_BACKEND_ENV=vercel

Custom IP Backend

# Example for a backend running on another machine in your network
VITE_GRAPHQL_ENDPOINT=http://192.168.1.100:8000/graphql/
VITE_BACKEND_URL=http://192.168.1.100:8000
VITE_BACKEND_ENV=custom

Development Workflow

Testing with Localhost Backend

Ensure your local backend is running on port 8000
Switch to localhost: npm run backend:local
Start frontend: npm run dev
Test API connectivity and image uploads

Testing with Vercel Backend

Switch to Vercel: npm run backend:vercel
Start frontend: npm run dev
Test against production backend environment

Testing with Custom IP Backend

Ensure the backend is running on the target machine
Open the Backend switcher UI
Enter the IP address and port (e.g., 192.168.1.100:8000)
Click “Apply” to save and switch
Update your .env.local file with the custom endpoint
Restart the frontend dev server

Common Use Cases for Custom IP:

Testing from mobile devices on the same network
Developing on multiple machines
Remote development scenarios
Testing backend changes without deploying

Troubleshooting

Connection Issues

If you see connection errors:

Check Backend Status: Use the “Test Connection” button in the dev UI
Verify URLs: Ensure the backend URLs are correct for your environment
CORS Issues: Localhost backend should allow http://localhost:8080 origin
Firewall: Ensure no firewall is blocking the connection

Environment Not Switching

If the backend doesn’t switch:

Restart Dev Server: Environment variables are loaded at startup
Clear Browser Cache: Force reload with Ctrl+F5
Check .env.local: Verify the file contains the correct configuration

Backend Switcher UI Not Visible

The switcher only appears in development mode. Ensure:

You’re running npm run dev (not a production build)
import.meta.env.DEV is true
Check browser console for any JavaScript errors

Mobile Visibility Issues

The backend switcher is now mobile-responsive:

On mobile devices, the button appears at the bottom-center
On desktop, it remains in the bottom-right corner
The switcher panel is responsive and fits mobile screens

Console Logging

The application logs backend configuration on startup:

🔧 Backend Configuration: {
  endpoint: "http://localhost:8000/graphql/",
  environment: "localhost", 
  isLocalhost: true
}

Look for these logs to verify your backend configuration is correct.

Security Notes

Environment files containing localhost URLs should not be committed to production
The .env.local file is gitignored and auto-managed
The backend switcher UI only appears in development mode for security
Custom IP addresses are stored in localStorage and persist across sessions
Ensure your backend server has proper CORS configuration for custom IPs
Never expose sensitive backend endpoints to public networks

Search Results: