Next.js Plugin

Automatically expose your Next.js dev server via OutRay tunnel

The @outray/next plugin automatically creates an OutRay tunnel when your Next.js development server starts, giving you a public URL to share your local development environment.

npm install @outray/next

pnpm add @outray/next

yarn add @outray/next

Wrap your Next.js configuration with the plugin:

// next.config.ts
import withOutray from '@outray/next'

export default withOutray({
  // your Next.js config
})

When you run next dev or npm run dev, you'll see your tunnel URL printed in the terminal:

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

The plugin accepts an options object as the second argument:

// next.config.ts
import withOutray from '@outray/next'

export default withOutray(
  {
    // your Next.js config
  },
  {
    subdomain: 'my-app',
    apiKey: process.env.OUTRAY_API_KEY,
  }
)

Options

The plugin respects the following environment variables:

Custom Subdomain

Reserve a consistent subdomain for your project:

// next.config.ts
import withOutray from '@outray/next'

export default withOutray(
  {
    // your Next.js config
  },
  {
    subdomain: 'my-app',
    apiKey: process.env.OUTRAY_API_KEY,
  }
)

Custom Domain

Use your own domain for the tunnel:

// next.config.ts
import withOutray from '@outray/next'

export default withOutray(
  {},
  {
    customDomain: 'dev.example.com',
    apiKey: process.env.OUTRAY_API_KEY,
  }
)

Conditional Enabling

Only enable the tunnel in certain environments:

// next.config.ts
import withOutray from '@outray/next'

export default withOutray(
  {},
  {
    enabled: process.env.EXPOSE_TUNNEL === 'true',
  }
)

With Callbacks

React to tunnel events in your application:

// next.config.ts
import withOutray from '@outray/next'

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

Silent Mode

Disable all tunnel logs:

// next.config.ts
import withOutray from '@outray/next'

export default withOutray(
  {},
  {
    silent: true,
    onTunnelReady: (url) => {
      // Handle the URL silently
    },
  }
)

With Other Plugins

Compose with other Next.js plugins:

// next.config.ts
import withOutray from '@outray/next'
import withBundleAnalyzer from '@next/bundle-analyzer'

const config = {
  // your Next.js config
}

export default withOutray(
  withBundleAnalyzer({ enabled: process.env.ANALYZE === 'true' })(config),
  {
    subdomain: 'my-app',
  }
)

App Router & Pages Router

The plugin works seamlessly with both Next.js App Router and Pages Router. No additional configuration is required.

The plugin supports Next.js versions 13.x, 14.x, and 15.x.

Tunnel not starting

• Ensure you're running in development mode (next dev)
• Check that OUTRAY_ENABLED is not set to "false"
• Verify the PORT environment variable matches your dev server port

Authentication errors

• Run outray login in your terminal to authenticate
• Or set the OUTRAY_API_KEY environment variable

Connection issues

• Check your internet connection
• Verify the server URL is correct (default: wss://api.outray.dev/)
• The plugin will automatically attempt to reconnect on connection loss

Turbopack compatibility

The plugin works with both webpack and Turbopack. The tunnel is started during the webpack configuration phase, which runs even when using Turbopack for development.