Vite HTTP/2 Proxy Plugin

Vite plugin that provides HTTP/2 proxy support with full feature parity to Vite's built-in proxy.

Features

• 🚀 Native HTTP/2 Support - Uses Node's native http2 module, no intermediate proxy module.
• 🔄 Connection Pooling - Efficient HTTP/2 connection reuse with automatic cleanup.
• 🔌 WebSocket Support - Full WebSocket proxying with HTTP/2 upgrade handling.
• 🍪 Cookie Management - Advanced cookie rewriting with domain and path support.
• 🔒 Security Features - SSL validation, authentication, and X-Forwarded headers.
• 📡 SSE Support - Server-Sent Events with buffering control.
• 🛣️ Advanced Routing - Dynamic routing with function support.
• 📊 Comprehensive Logging - Detailed request logging with timing information.
• 🎯 Full Vite Compatibility - Supports Vite standard proxy configuration options.

Installation

npm install vite-plugin-proxy-http2
# or
yarn add vite-plugin-proxy-http2
# or
pnpm add vite-plugin-proxy-http2

Quick Start

Recommended: Plugin-level Configuration (HTTP/2 by default)

// vite.config.ts
import { defineConfig } from 'vite'
import http2ProxyPlugin from 'vite-plugin-proxy-http2'

export default defineConfig({
  plugins: [
    http2ProxyPlugin({
      // Global settings (optional)
      maxSessions: 50,              // Limit HTTP/2 sessions
      defaultTimeout: 30000,        // 30 second timeout for all proxies
      
      // Proxy routes
      proxy: {
        '/api': 'https://api.example.com',
        '/ws': {
          target: 'wss://websocket.example.com',
          ws: true
        }
      }
    })
  ]
})

Note: This approach ensures HTTP/2 is used by default and prevents Vite from downgrading to HTTP/1.1.

Alternative: Vite Server Configuration

// vite.config.ts
import { defineConfig } from 'vite'
import http2ProxyPlugin from 'vite-plugin-proxy-http2'

export default defineConfig({
  plugins: [http2ProxyPlugin()],
  server: {
    proxy: {
      '/api': 'https://api.example.com'
    }
  }
})

Warning: Using Vite's server.proxy may cause Vite to downgrade connections to HTTP/1.1. We recommend using the plugin-level configuration instead.

Configuration

Basic Examples

export default defineConfig({
  plugins: [
    http2ProxyPlugin({
      proxy: {
        // String shorthand
        '/api': 'https://api.example.com',
        
        // With options
        '/api': {
          target: 'https://api.example.com',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, ''),
          headers: {
            'X-Custom-Header': 'value'
          }
        },
        
        // RegExp pattern
        '^/api/.*': {
          target: 'https://api.example.com',
          changeOrigin: true
        }
      }
    })
  ]
})

Advanced Features

WebSocket Support

'/socket.io': {
  target: 'https://socket-server.com',
  ws: true,
  changeOrigin: true
}

Cookie Rewriting

'/api': {
  target: 'https://api.example.com',
  cookieDomainRewrite: 'localhost',
  cookiePathRewrite: {
    '/api': '/',
    '/api/v2': '/v2'
  }
}

Dynamic Routing

'/api': {
  target: 'https://default-api.com',
  router: (req) => {
    // Route based on headers, query params, etc.
    if (req.headers['x-api-version'] === 'v2') {
      return 'https://api-v2.example.com'
    }
    return 'https://api-v1.example.com'
  }
}

Conditional Bypass

'/api': {
  target: 'https://api.example.com',
  bypass: (req, res, options) => {
    // Skip proxy for certain conditions
    if (req.headers.accept?.includes('text/html')) {
      return '/index.html'
    }
  }
}

Protocol Support (HTTP/1.1 and HTTP/2)

// Force HTTP/1.1 for servers that don't support HTTP/2
'/legacy-api': {
  target: 'https://old-server.com',
  forceHttp1: true
}

// Automatically detect protocol support
'/auto': {
  target: 'https://api.example.com',
  autoDetectProtocol: true // Will use HTTP/2 if supported, fallback to HTTP/1.1
}

Security Options

'/api': {
  target: 'https://api.example.com',
  secure: true, // Verify SSL certificates
  auth: 'username:password', // Basic authentication
  xfwd: true, // Add X-Forwarded-* headers
  headers: {
    'Authorization': 'Bearer token'
  }
}

Timeout Configuration

http2ProxyPlugin({
  // Set global defaults for all proxies
  defaultTimeout: 30000,        // 30 seconds
  defaultProxyTimeout: 25000,   // 25 seconds
  
  proxy: {
    '/api': 'https://api.example.com',  // Uses global defaults
    
    '/slow-api': {
      target: 'https://slow-api.example.com',
      timeout: 60000  // Override for specific route
    }
  }
})

Server-Sent Events

'/events': {
  target: 'https://sse-server.com',
  sse: true, // Optimizes for SSE streams
  changeOrigin: true
}

Custom Response Handling

'/api': {
  target: 'https://api.example.com',
  selfHandleResponse: true,
  configure: (proxyReq, options) => {
    // Custom request/response handling
    proxyReq.on('response', (headers) => {
      console.log('Response headers:', headers)
    })
  }
}

Configuration Options

Global Plugin Options

These options are configured at the plugin level and affect all proxies:

Option	Type	Default	Description
proxy	object	-	Proxy route configurations
maxSessions	number	100	Maximum number of HTTP/2 sessions
sessionMaxAge	number	300000	Session idle timeout in milliseconds (5 minutes)
connectionTimeout	number	10000	Initial connection timeout in milliseconds
maxQueueSize	number	100	Maximum queued requests across all origins
queueTimeout	number	30000	Queue timeout in milliseconds
defaultTimeout	number	120000	Default timeout for all proxies in milliseconds
defaultProxyTimeout	number	-	Default proxy-specific timeout in milliseconds

Example:

http2ProxyPlugin({
  // Global settings
  maxSessions: 50,
  sessionMaxAge: 2 * 60 * 1000, // 2 minutes
  maxQueueSize: 200,
  defaultTimeout: 30000, // 30 seconds
  
  // Proxy routes
  proxy: {
    '/api': 'https://api.example.com'
  }
})

Per-Proxy Options

These options can be configured for each individual proxy route:

Option	Type	Default	Description
target	string | object	required	Backend server URL
changeOrigin	boolean	true	Changes the origin header to match the target
ws	boolean	false	Enable WebSocket proxy
rewrite	function	-	Rewrite request paths
configure	function	-	Custom proxy configuration callback
bypass	function	-	Conditionally bypass the proxy
secure	boolean	true	Verify SSL certificates
auth	string	-	Basic authentication credentials
headers	object	-	Custom headers to add to requests
forceHttp1	boolean	false	Force HTTP/1.1 protocol for this proxy
autoDetectProtocol	boolean	false	Auto-detect if origin supports HTTP/2
xfwd	boolean	true	Add X-Forwarded-* headers
preserveHeaderKeyCase	boolean	false	Preserve original header key casing
cookieDomainRewrite	string | object	-	Rewrite cookie domains
cookiePathRewrite	string | object	-	Rewrite cookie paths
router	string | function	-	Dynamic target routing
timeout	number	global default	Proxy timeout in milliseconds (overrides global)
proxyTimeout	number	global default	Proxy timeout in milliseconds (overrides global)
selfHandleResponse	boolean	false	Handle response manually
followRedirects	boolean	false	Follow HTTP redirects
sse	boolean	false	Optimize for Server-Sent Events

Debugging

Enable debug logging by setting the DEBUG environment variable:

DEBUG=vite:http2-proxy npm run dev

Or set LOG_LEVEL for more detailed logging:

LOG_LEVEL=debug npm run dev

Performance

The plugin implements several performance optimizations:

• Connection Pooling: Reuses HTTP/2 connections across requests
• Automatic Cleanup: Removes idle connections after configurable timeout (default: 5 minutes)
• Connection Limits: Prevents resource exhaustion with configurable session limits (default: 100)
• Request Queueing: Handles high load with configurable queue size (default: 100 requests)
• Stream Management: Proper HTTP/2 stream lifecycle handling
• Timeout Handling: Configurable timeouts prevent hanging requests

Migration from http-proxy

This plugin maintains API compatibility with Vite's built-in proxy (which uses http-proxy). Simply install and add the plugin to migrate:

// vite.config.ts
import { defineConfig } from 'vite'
+import http2ProxyPlugin from 'vite-http2-proxy'

export default defineConfig({
+  plugins: [http2ProxyPlugin({
+    proxy: {
+      // Your existing proxy config works as-is,
+      // just move it into the plugin config
+      '/api': 'https://api.example.com'
+    }
  })],
  server: {
    // Remove proxy config from here
  }
})

Troubleshooting

Common Issues

1. SSL Certificate Errors

   // Disable SSL verification for development
   '/api': {
     target: 'https://self-signed.example.com',
     secure: false
   }

2. Cookie Issues

   // Ensure cookies work on localhost
   '/api': {
     target: 'https://api.example.com',
     cookieDomainRewrite: 'localhost',
     cookiePathRewrite: '/'
   }

3. Timeout Errors

   // Increase timeout for slow endpoints
   '/api': {
     target: 'https://slow-api.example.com',
     timeout: 300000 // 5 minutes
   }

License

MIT