Vite React QR Share 📱

A stable and production-ready Vite plugin for sharing your React development server with mobile devices via QR code. Perfect for testing your app on phones and tablets without ngrok or other external services.

Features

✅ Zero Configuration - Works out of the box
✅ Stable Mobile Access - Tested on various networks and devices
✅ Intelligent IP Detection - Automatically detects your Wi-Fi IP
✅ QR Code Terminal Display - Scan to open in browser instantly
✅ Customizable - Fine-tune behavior with options
✅ TypeScript Support - Full type definitions included
✅ HMR Disabled by Default - Prevents mobile disconnection issues
✅ CLI Setup Tool - One command to configure everything

🚀 Quick Setup with CLI

The fastest way to get started:

npx vite-react-qr-share

The CLI will:

• ✅ Validate your Vite + React project
• ✅ Find your vite.config.js
• ✅ Show recommended configuration
• ✅ Display step-by-step setup instructions

No installation needed! See CLI-SETUP.md for more details.

Why This Package?

After extensive testing across multiple network topologies (including VMware virtual adapters), we've discovered the optimal configuration for stable mobile access:

1. Bind to all interfaces (0.0.0.0)
2. Disable HMR by default (prevents WebSocket issues on mobile)
3. Smart IP detection (prioritize real adapters over virtual ones)
4. Display QR code (easy mobile access)

Installation

npm install --save-dev vite-react-qr-share

Quick Start

1. Basic Usage

Add to your vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import vitQRShare from 'vite-react-qr-share'

export default defineConfig({
  plugins: [react(), vitQRShare()],
  server: {
    host: '0.0.0.0',
    port: 5173,
    hmr: false
  }
})

2. Using Helper Functions

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import vitQRShare, { getServerConfig, getBuildConfig } from 'vite-react-qr-share'

export default defineConfig({
  plugins: [react(), vitQRShare()],
  server: getServerConfig(),
  build: getBuildConfig()
})

3. With Custom Options

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import vitQRShare from 'vite-react-qr-share'

export default defineConfig({
  plugins: [
    react(),
    vitQRShare({
      enabled: true,
      showUrl: true,
      showQR: true,
      onReady: ({ url, host, port }) => {
        console.log(`Server ready at ${url}`)
      }
    })
  ],
  server: {
    host: '0.0.0.0',
    port: 5173,
    hmr: false
  }
})

Configuration Options

Plugin Options

interface VitQRShareOptions {
  // Enable or disable the plugin (default: true)
  enabled?: boolean

  // IP address to prefer for QR code (if available)
  preferredIP?: string

  // Show server URL in console (default: true)
  showUrl?: boolean

  // Show QR code in console (default: true)
  showQR?: boolean

  // Callback when server is ready
  onReady?: (info: { url: string; host: string; port: number; protocol: string }) => void
}

Server Configuration

interface ServerConfig {
  host: string      // '0.0.0.0' - bind to all interfaces
  port: number      // 5173 - dev server port
  strictPort: boolean // false - use next available port if busy
  hmr: false | object // false for mobile stability
}

Typical Use Case

Development with Mobile Testing:

# Terminal 1 - Start dev server
npm run dev
# Output: 
# ╔════════════════════════════════════════╗
# ║   📱 Vite QR Share - Mobile Ready      ║
# ╚════════════════════════════════════════╝
#
# 🔗 Server URL: http://192.168.1.100:5173
# [QR CODE DISPLAYED HERE]

# Terminal 2 - Point mobile browser to URL or scan QR
# On mobile browser: http://192.168.1.100:5173

API Reference

vitQRShare(options?)

Main Vite plugin function.

import vitQRShare from 'vite-react-qr-share'

export default {
  plugins: [vitQRShare(options)]
}

getLocalWifiIP(options?)

Manually detect local Wi-Fi IP address.

import { getLocalWifiIP } from 'vite-react-qr-share'

const ip = getLocalWifiIP()
// Returns: '192.168.1.100' or similar

// With preferred IP
const ip = getLocalWifiIP({ preferredIP: '192.168.1.50' })

getServerConfig(options?)

Get recommended server configuration.

import { getServerConfig } from 'vite-react-qr-share'

const serverConfig = getServerConfig({
  port: 3000,
  enableHMR: false
})

getBuildConfig(options?)

Get recommended build configuration.

import { getBuildConfig } from 'vite-react-qr-share'

const buildConfig = getBuildConfig({
  outDir: 'dist'
})

getAvailableNetworks()

Get all available network interfaces.

import { getAvailableNetworks } from 'vite-react-qr-share'

const networks = getAvailableNetworks()
// Returns: [
//   { adapter: 'Wi-Fi', ip: '192.168.1.100', netmask: '255.255.255.0', mac: '...' },
//   { adapter: 'Ethernet', ip: '10.0.0.50', ... }
// ]

Troubleshooting

"Mobile can't connect to server"

1. Ensure same Wi-Fi network: Both PC and mobile must be on same Wi-Fi
2. Check firewall: Windows Firewall may block connections
3. Restart Wi-Fi: Sometimes helps with routing cache
4. Use correct IP: Check that QR code shows correct IP (192.168.x.x, not 127.0.0.1)

"Only localhost works, not from phone"

This is the HMR WebSocket issue. The plugin disables HMR by default to prevent this. If you need HMR:

vitQRShare({
  onReady: ({ host, port }) => {
    console.log(`Connect with HMR at ${host}:${port}`)
  }
}),

And configure HMR properly:

server: {
  host: '0.0.0.0',
  hmr: {
    host: 'your-wifi-ip-here',
    port: 5173
  }
}

"Getting wrong IP (virtual adapter instead of Wi-Fi)"

The plugin automatically prioritizes real adapters. If it still detects wrong IP:

vitQRShare({
  preferredIP: '192.168.1.100' // Your actual Wi-Fi IP
})

Real-World Example

Complete vite.config.js for production use:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import vitQRShare, { getServerConfig, getBuildConfig } from 'vite-react-qr-share'

export default defineConfig({
  plugins: [
    react(),
    vitQRShare({
      enabled: true,
      onReady: ({ url }) => {
        console.log(`🚀 Ready to test on mobile: ${url}`)
      }
    })
  ],
  server: getServerConfig({
    port: 5173,
    enableHMR: false
  }),
  build: getBuildConfig({
    outDir: 'dist'
  })
})

Network Topology Tested

This package has been tested on:

• ✅ Single Wi-Fi adapter (standard setup)
• ✅ Multiple Ethernet adapters
• ✅ VMware virtual adapters (prioritizes real adapter)
• ✅ Dual Wi-Fi (2.4GHz + 5GHz)
• ✅ VPN connections
• ✅ Mesh networks
• ✅ Hotspot sharing

Contributing

Found a bug or have a suggestion? Open an issue on GitHub

License

MIT - Feel free to use in personal and commercial projects

Support

Need help? Check the GitHub Issues or create a new one

Made with ❤️ for React developers who love testing on real devices