Vite Port Forwarding Test

A minimal Vite + React project designed to test and reproduce port forwarding issues in Gitpod/Ona environments. This project is inspired by production Vite configurations and includes diagnostic tools to verify port forwarding behavior.

Overview

This test environment simulates a typical Vite development server setup with:

• Port 3002 configuration
• Proxy configuration for API routes
• Host binding to 0.0.0.0 for external access
• Interactive UI for testing port forwarding and proxy functionality

Project Structure

.
├── src/
│   ├── App.tsx           # Main React component with diagnostics UI
│   ├── main.tsx          # React entry point
│   └── index.css         # Basic styles
├── index.html            # HTML entry point
├── vite.config.ts        # Vite configuration with port and proxy settings
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── tsconfig.node.json    # TypeScript config for Vite config file

Configuration Details

Vite Server Configuration

The vite.config.ts includes key settings for port forwarding:

server: {
  port: 3002,
  host: '0.0.0.0',        // Required for external access
  allowedHosts: true,      // Allows all hosts (including Gitpod URLs)
  strictPort: true,
  proxy: {
    '/api': {
      target: 'https://jsonplaceholder.typicode.com',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
}

Important Notes:

• host: '0.0.0.0' is required for Gitpod/Ona port forwarding to work
• host: '127.0.0.1' will result in "Service Unavailable" errors
• allowedHosts: true allows access from Gitpod's dynamic URLs
• See Ona Ports Documentation for more info

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• npm or yarn

Installation

npm install

Running the Development Server

npm run dev

The server will start on port 3002. In Gitpod/Ona environments, the port will be automatically forwarded.

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build

Testing Port Forwarding

Once the server is running, the UI provides several diagnostic features:

1. Server Information Panel

Displays:

• Configured port (3002)
• Current host
• Protocol (http/https)
• Full URL

2. Proxy Test

• Click "Test Proxy" button to verify proxy configuration
• Makes a request to /api/posts/1 which is proxied to jsonplaceholder.typicode.com
• Shows success/error status and response data

3. Port Forwarding Notes

Lists key configuration details to verify during testing

Troubleshooting

403 Forbidden Error

If you receive a 403 error when accessing the forwarded URL:

1. Check host binding:

   // ❌ Wrong - will cause 403
   host: '127.0.0.1'
   
   // ✅ Correct
   host: '0.0.0.0'

2. Verify allowedHosts:

   // Option 1: Allow all hosts
   allowedHosts: true
   
   // Option 2: Specify allowed hosts
   allowedHosts: ['.flex.doptig.cloud', 'localhost']

3. Check port status:

   gitpod environment port list

Port Not Accessible

1. Verify server is running:

   curl http://localhost:3002

2. Check if port is forwarded:

   gitpod environment port list

3. Restart the server:

   • Stop the current server (Ctrl+C)
   • Run npm run dev again

Proxy Not Working

1. Check browser console for CORS or network errors
2. Verify proxy configuration in vite.config.ts
3. Test direct access to the proxy target URL

Common Issues Reproduced

This test environment can help reproduce:

• ✅ Port forwarding with host: '0.0.0.0' vs host: '127.0.0.1'
• ✅ allowedHosts configuration issues
• ✅ Proxy configuration in forwarded environments
• ✅ HTTPS/HTTP protocol handling
• ✅ Dynamic URL patterns in Gitpod/Ona

Dependencies

Runtime

• react ^18.2.0
• react-dom ^18.2.0

Development

• vite ^5.0.0
• @vitejs/plugin-react ^4.2.0
• typescript ^5.3.0
• @types/react ^18.2.0
• @types/react-dom ^18.2.0

Reference Configuration

This project is based on a production Vite configuration that includes:

• React with SWC plugin
• Lingui for internationalization
• Sentry integration
• Bundle analyzer
• Complex proxy setup for multiple API routes

The test environment simplifies this to focus on port forwarding behavior while maintaining the essential configuration patterns.

Gitpod/Ona Commands

Useful commands for managing ports in Gitpod/Ona:

# List all forwarded ports
gitpod environment port list

# Open a port (if not already open)
gitpod environment port open <port>

# Close a port
gitpod environment port close <port>

License

This is a test project for reproducing customer issues. Use freely for debugging and testing purposes.