Vite Plugin

Automatically expose your Vite dev server to the internet with a single plugin entry.

The @outray/vite plugin integrates with Vite’s configureServer hook to start an OutRay tunnel as soon as the dev server begins listening. The tunnel URL appears in the terminal alongside Vite’s local and network URLs.

The plugin uses apply: "serve" and only runs during vite dev. It is completely inactive during builds.

Setup

1. Install the package

   npm

   npm install @outray/vite
   
2. Add the plugin to your Vite config

   Import outray and add it to the plugins array in vite.config.ts:

   vite.config.ts

   import { defineConfig } from 'vite'
   import outray from '@outray/vite'
   
   export default defineConfig({
     plugins: [outray()]
   })
   
3. Start the dev server

   Run vite or npm run dev. The tunnel URL appears alongside the local address:

     ➜  Local:   http://localhost:5173/
     ➜  Tunnel:  https://abc123.outray.dev
   

Configuration

Pass an options object to outray():

vite.config.ts

import { defineConfig } from 'vite'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [
    outray({
      subdomain: 'my-app',
      apiKey: process.env.OUTRAY_API_KEY,
    })
  ]
})

Options

Option	Type	Default	Description
subdomain	string	—	Request a specific subdomain. Requires authentication.
customDomain	string	—	Use a custom domain configured in the OutRay dashboard.
apiKey	string	process.env.OUTRAY_API_KEY	API key for authentication.
serverUrl	string	wss://api.outray.dev/	OutRay server WebSocket URL. Change this only for self-hosted instances.
enabled	boolean	process.env.OUTRAY_ENABLED !== "false"	Enable or disable the tunnel.
silent	boolean	false	Suppress all tunnel status logs.
local	boolean	false	Enable LAN access via mDNS (.local domain) for devices on the same network.
onTunnelReady	(url: string) => void	—	Called when the tunnel is established.
onLocalReady	(info: LocalInfo) => void	—	Called when LAN access is available.
onError	(error: Error) => void	—	Called when the tunnel encounters an error.
onClose	() => void	—	Called when the tunnel connection closes.
onReconnecting	() => void	—	Called when the tunnel is attempting to reconnect.

Environment variables

Variable	Description
OUTRAY_API_KEY	API key for authentication — fallback for the apiKey option.
OUTRAY_SUBDOMAIN	Subdomain to request — fallback for the subdomain option.
OUTRAY_SERVER_URL	Server WebSocket URL — fallback for the serverUrl option.
OUTRAY_ENABLED	Set to "false" to disable the tunnel without removing the plugin.

Examples

Custom subdomain

Reserve a consistent URL for your project:

vite.config.ts

import { defineConfig } from 'vite'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [
    outray({
      subdomain: 'my-app',
      apiKey: process.env.OUTRAY_API_KEY,
    })
  ]
})

Custom domain

Use a domain you’ve configured in the OutRay dashboard:

vite.config.ts

import { defineConfig } from 'vite'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [
    outray({
      customDomain: 'dev.example.com',
      apiKey: process.env.OUTRAY_API_KEY,
    })
  ]
})

Callbacks

React to tunnel lifecycle events:

vite.config.ts

import { defineConfig } from 'vite'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [
    outray({
      onTunnelReady: (url) => {
        console.log(`Share this URL: ${url}`)
      },
      onError: (error) => {
        console.error('Tunnel error:', error.message)
      },
      onReconnecting: () => {
        console.log('Connection lost, reconnecting...')
      },
    })
  ]
})

Silent mode

Suppress all console output and handle the URL yourself:

vite.config.ts

import { defineConfig } from 'vite'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [
    outray({
      silent: true,
      onTunnelReady: (url) => {
        // store or forward url as needed
      },
    })
  ]
})

Framework integration

The plugin works with any Vite-based framework. Add it alongside your existing framework plugin:

React

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [react(), outray()]
})

Vue

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [vue(), outray()]
})

Svelte

vite.config.ts

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [svelte(), outray()]
})

SolidJS

vite.config.ts

import { defineConfig } from 'vite'
import solid from 'vite-plugin-solid'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [solid(), outray()]
})

TypeScript

The package exports OutrayPluginOptions for typed configuration:

vite.config.ts

import { defineConfig } from 'vite'
import outray from '@outray/vite'
import type { OutrayPluginOptions } from '@outray/vite'

const outrayOptions: OutrayPluginOptions = {
  subdomain: 'my-app',
  apiKey: process.env.OUTRAY_API_KEY,
  onTunnelReady: (url: string) => {
    console.log(`Tunnel ready: ${url}`)
  },
}

export default defineConfig({
  plugins: [outray(outrayOptions)]
})

The full OutrayPluginOptions interface:

interface OutrayPluginOptions {
  subdomain?: string
  customDomain?: string
  apiKey?: string
  serverUrl?: string
  enabled?: boolean
  silent?: boolean
  local?: boolean
  onTunnelReady?: (url: string) => void
  onLocalReady?: (info: {
    hostname: string
    ip: string
    httpUrl?: string
    httpsUrl?: string
  }) => void
  onError?: (error: Error) => void
  onClose?: () => void
  onReconnecting?: () => void
}

Compatibility

• Vite: 4.x, 5.x, 6.x, 7.x
• Servers: TCP ports only — Unix domain sockets are not supported.

Troubleshooting

Tunnel not starting

• Confirm your Vite dev server is listening on a TCP port.
• Check that OUTRAY_ENABLED is not set to "false".
• Verify your API key is valid if using a reserved subdomain.

Authentication errors

• Run outray login to authenticate, or set OUTRAY_API_KEY.

Connection issues

• The plugin reconnects automatically on connection loss.
• Confirm the server URL is correct (default: wss://api.outray.dev/).