### GitHub Actions: Start OutRay Tunnel

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(platform-features)/ci-cd.mdx

This example shows how to set up a GitHub Action to install the OutRay CLI and start a tunnel. It uses a GitHub secret for the API key and runs the tunnel in the background.

```yaml
steps:
  - name: Start Tunnel
    run: |
      npm install -g outray
      outray 3000 --key ${{ secrets.OUTRAY_API_KEY }} &

```

--------------------------------

### Install OutRay CLI Globally with npm

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/getting-started/installation.mdx

Installs the OutRay CLI globally on your system using npm, making the 'outray' command available system-wide. Requires Node.js (version 18 or higher) and npm.

```bash
npm install -g outray
```

--------------------------------

### Example Usage of OutRay CLI Commands

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Demonstrates common usage patterns for OutRay CLI commands, including validating configuration files and starting tunnels from default or custom configuration files.

```bash
# Validate your config file first
outray validate-config

# Start all tunnels from outray/config.toml
outray start

# Start tunnels from a custom config file
outray start --config production.toml
```

--------------------------------

### Verify OutRay CLI Installation

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/getting-started/installation.mdx

Checks if the OutRay CLI has been installed successfully by displaying its version number. This command should be run after installation.

```bash
outray --version
```

--------------------------------

### OutRay TOML Configuration File Example

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Defines multiple tunnels with global and specific settings using TOML format. This file can be used with the `outray start` command to manage multiple tunnels simultaneously.

```toml
[global]
org = "my-team"
server_url = "wss://api.outray.dev/"

[tunnel.web]
protocol = "http"
local_port = 3000
local_host = "localhost"
subdomain = "my-app"
custom_domain = "app.example.com"

[tunnel.api]
protocol = "http"
local_port = 8000
subdomain = "api"

[tunnel.postgres]
protocol = "tcp"
local_port = 5432
local_host = "localhost"
remote_port = 20000

[tunnel.game-server]
protocol = "udp"
local_port = 5000
remote_port = 30000
```

--------------------------------

### Automate OutRay Tunnel Creation via CLI

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(platform-features)/ci-cd.mdx

This snippet demonstrates how to start an OutRay tunnel using the command-line interface with an API key for authentication. It requires the OutRay CLI to be installed and an API key stored as an environment variable.

```bash
outray 3000 --key $OUTRAY_API_KEY
```

--------------------------------

### Outray CLI: Start and Validate Configuration

Source: https://context7.com/akinloluwami/outray/llms.txt

Commands to start Outray tunnels using a configuration file. Supports default and custom configuration paths.

```bash
# Start all tunnels from config
outray start

# Use custom config path
outray start --config ./custom/config.toml
outray validate-config --config ./custom/config.toml
```

--------------------------------

### Install @outray/core Package

Source: https://github.com/akinloluwami/outray/blob/main/packages/core/README.md

Instructions for installing the @outray/core package using npm, pnpm, or yarn. This package is essential for setting up the Outray tunnel client.

```bash
npm install @outray/core
# or
pnpm add @outray/core
# or
yarn add @outray/core
```

--------------------------------

### Install @outray/core Package

Source: https://context7.com/akinloluwami/outray/llms.txt

Installs the @outray/core package using npm. This is the first step to using the library in your project.

```bash
npm install @outray/core
```

--------------------------------

### Expose Local Server via Outray CLI

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(getting-started)/opening-a-tunnel.mdx

Starts a tunnel to expose a local server running on a specified port to the internet. Requires the Outray CLI to be installed. Accepts a port number as input and outputs connection status and the public tunnel URL.

```bash
outray 3000
```

--------------------------------

### Install @outray/vite Plugin

Source: https://context7.com/akinloluwami/outray/llms.txt

Install the @outray/vite plugin using npm. This is the first step to enable automatic exposure of your Vite development server.

```bash
npm install @outray/vite
```

--------------------------------

### Start All Tunnels from Outray Configuration

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(getting-started)/opening-a-tunnel.mdx

Starts all tunnels defined in the Outray TOML configuration file. This command reads the configuration and establishes tunnels for each defined service. Requires a valid configuration file.

```bash
outray start
```

--------------------------------

### CLI Installation and Management

Source: https://context7.com/akinloluwami/outray/llms.txt

Commands to install, verify, update, and uninstall the Outray CLI globally using npm. Ensures the CLI is accessible for managing tunnels.

```bash
# Install globally via npm
npm install -g outray

# Verify installation
outray --version

# Update to latest version
npm install -g outray@latest

# Uninstall
npm uninstall -g outray
```

--------------------------------

### Update OutRay CLI to Latest Version with npm

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/getting-started/installation.mdx

Updates the OutRay CLI to the most recent version available on npm. This command re-installs the package, ensuring you have the latest features and fixes.

```bash
npm install -g outray@latest
```

--------------------------------

### Start OutRay Tunnels from Configuration

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Starts multiple tunnels defined in a TOML configuration file. This command can use the default configuration file or a custom one specified via the --config flag.

```bash
# Use default outray/config.toml
outray start

# Use a custom config file
outray start --config /path/to/config.toml
```

--------------------------------

### Install Next.js Plugin for Outray

Source: https://context7.com/akinloluwami/outray/llms.txt

Install the `@outray/next` npm package to integrate Outray with your Next.js application.

```bash
npm install @outray/next
```

--------------------------------

### Install @outray/vite Plugin

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Install the OutRay Vite plugin using npm, pnpm, or yarn. This is the first step to integrating OutRay with your Vite project.

```bash
npm install @outray/vite
```

```bash
pnpm add @outray/vite
```

```bash
yarn add @outray/vite
```

--------------------------------

### Basic Tunnel Client Usage with @outray/core

Source: https://context7.com/akinloluwami/outray/llms.txt

Demonstrates the basic usage of the OutrayClient for managing tunnels. It shows how to configure the client with options like local port, server URL, API key, subdomain, and custom domain, and how to handle tunnel events like readiness, errors, and connection closures. The client can be started, its connection status checked, and its URL retrieved. It also includes graceful shutdown handling.

```typescript
// Basic tunnel client usage
import { OutrayClient } from '@outray/core'

const client = new OutrayClient({
  // Required: local port to proxy requests to
  localPort: 3000,

  // Optional: Outray server URL (default: wss://api.outray.dev/)
  serverUrl: 'wss://api.outray.dev/',

  // Optional: API key for authentication
  apiKey: process.env.OUTRAY_API_KEY,

  // Optional: request a specific subdomain
  subdomain: 'my-app',

  // Optional: use a custom domain
  customDomain: 'dev.example.com',

  // Optional: tunnel protocol (http, tcp, udp)
  protocol: 'http',

  // Optional: remote port for TCP/UDP tunnels
  remotePort: 20000,

  // Callback when tunnel is ready
  onTunnelReady: (url, port) => {
    console.log(`Tunnel URL: ${url}`)
    if (port) console.log(`Remote port: ${port}`)
  },

  // Callback on error
  onError: (error, code) => {
    console.error(`Error [${code}]: ${error.message}`)
    // Error codes: SUBDOMAIN_IN_USE, AUTH_FAILED, LIMIT_EXCEEDED,
    //              INVALID_SUBDOMAIN, CUSTOM_DOMAIN_NOT_CONFIGURED
  },

  // Callback when connection closes
  onClose: (reason) => {
    console.log(`Connection closed: ${reason}`)
  },

  // Callback when reconnecting
  onReconnecting: (attempt, delay) => {
    console.log(`Reconnecting (attempt ${attempt}) in ${delay}ms...`)
  },

  // Callback for each proxied request (HTTP only)
  onRequest: (info) => {
    console.log(`${info.method} ${info.path} ${info.statusCode} ${info.duration}ms`)
    if (info.error) console.error(`  Error: ${info.error}`)
  },
})

// Start the tunnel
client.start()

// Check connection status
if (client.isConnected()) {
  console.log('Connected!')
}

// Get the assigned URL
const url = client.getUrl()
console.log(`Tunnel URL: ${url}`)

// Stop the tunnel when done
process.on('SIGINT', () => {
  client.stop()
  process.exit(0)
})

```

--------------------------------

### Install @outray/next Plugin

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/nextjs-plugin.mdx

Installs the OutRay Next.js plugin using npm, pnpm, or yarn. This is the first step to integrating OutRay tunneling with your Next.js project.

```bash
npm install @outray/next
```

```bash
pnpm add @outray/next
```

```bash
yarn add @outray/next
```

--------------------------------

### Uninstall OutRay CLI with npm

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/getting-started/installation.mdx

Removes the OutRay CLI from your system. Use this command if you no longer need the OutRay command-line interface.

```bash
npm uninstall -g outray
```

--------------------------------

### Start Single OutRay Tunnel by Port

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Starts a tunnel for a specified local port, exposing it to the OutRay network. Optional flags allow specifying a subdomain, custom domain, organization, API key, or disabling logs.

```bash
outray 3000
```

--------------------------------

### Example: Custom Domain Configuration

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Set up the OutRay plugin to use your own custom domain for the tunnel. This requires prior configuration in the OutRay dashboard.

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

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

--------------------------------

### Configuration File Management

Source: https://context7.com/akinloluwami/outray/llms.txt

Example TOML configuration file structure for defining multiple tunnels with specific protocols, ports, and settings. Includes a command to validate the configuration file's syntax and structure.

```toml
# Global settings
[global]
org = "my-team"
# server_url = "wss://api.outray.dev/"  # Custom server URL (optional)

# HTTP tunnel for web app
[tunnel.web]
protocol = "http"
local_port = 3000
local_host = "localhost"
subdomain = "my-app"
custom_domain = "app.example.com"  # Optional

# HTTP tunnel for API server
[tunnel.api]
protocol = "http"
local_port = 8000
subdomain = "api"

# TCP tunnel for PostgreSQL
[tunnel.postgres]
protocol = "tcp"
local_port = 5432
local_host = "localhost"
remote_port = 20000

# UDP tunnel for game server
[tunnel.game-server]
protocol = "udp"
local_port = 5000
remote_port = 30000
```

```bash
# Validate configuration file
outray validate-config

# Expected output:
# ✓ Config file is valid
#
# Found 4 tunnel(s):
#
#   [web]
#     Protocol: http
#     Local: localhost:3000

```

--------------------------------

### Example: Using Callbacks for Tunnel Events

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Implement callback functions to react to tunnel events such as readiness, errors, reconnections, and closures. This allows for custom handling of tunnel status.

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

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

--------------------------------

### Configure Next.js Plugin: Composing with Other Plugins

Source: https://context7.com/akinloluwami/outray/llms.txt

Example of composing the Outray Next.js plugin with other Next.js plugins, such as `@next/bundle-analyzer`.

```typescript
// next.config.ts - Composing with other plugins
import withOutray from '@outray/next'
import withBundleAnalyzer from '@next/bundle-analyzer'

const config = {
  reactStrictMode: true,
}

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

--------------------------------

### Configure ESLint with React-Specific Rules (TypeScript)

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/README.md

This code demonstrates how to integrate `eslint-plugin-react-x` and `eslint-plugin-react-dom` into an ESLint configuration for React projects. It enables recommended lint rules for both React and React DOM, along with project-specific TypeScript configurations.

```javascript
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}']
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname
      },
      // other options...
    },
  },
])
```

--------------------------------

### Integrate @outray/vite with React

Source: https://context7.com/akinloluwami/outray/llms.txt

Configure the @outray/vite plugin alongside the React plugin in vite.config.ts. This example shows how to set a specific subdomain for your React application's tunnel.

```typescript
// vite.config.ts - With React
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [react(), outray({ subdomain: 'my-react-app' })]
})
```

--------------------------------

### Protocol Utilities for Custom Implementations with @outray/core

Source: https://context7.com/akinloluwami/outray/llms.txt

Illustrates the use of protocol utilities from @outray/core for custom message handling. It shows how to encode outgoing messages (like handshake requests) and decode incoming messages from the server. Examples include handling tunnel opened events, incoming data requests, and errors, as well as constructing response messages.

```typescript
// Using protocol utilities for custom implementations
import { encodeMessage, decodeMessage } from '@outray/core'
import type {
  OpenTunnelMessage,
  TunnelOpenedMessage,
  TunnelDataMessage,
  TunnelResponseMessage,
  ErrorMessage,
  ErrorCodes,
} from '@outray/core'

// Encode a message to send to the server
const handshake: OpenTunnelMessage = {
  type: 'open_tunnel',
  apiKey: 'your-api-key',
  subdomain: 'my-app',
  protocol: 'http',
}
const encoded = encodeMessage(handshake)

// Decode a message received from the server
const decoded = decodeMessage(data)

if (decoded.type === 'tunnel_opened') {
  const msg = decoded as TunnelOpenedMessage
  console.log(`Tunnel URL: ${msg.url}`)
} else if (decoded.type === 'request') {
  const msg = decoded as TunnelDataMessage
  // Handle incoming HTTP request
  console.log(`${msg.method} ${msg.path}`)
} else if (decoded.type === 'error') {
  const msg = decoded as ErrorMessage
  console.error(`Error [${msg.code}]: ${msg.message}`)
}

// Build a response
const response: TunnelResponseMessage = {
  type: 'response',
  requestId: 'request-123',
  statusCode: 200,
  headers: { 'content-type': 'application/json' },
  body: Buffer.from(JSON.stringify({ ok: true })).toString('base64'),
}

```

--------------------------------

### Integrate @outray/vite with Svelte

Source: https://context7.com/akinloluwami/outray/llms.txt

Configure the @outray/vite plugin alongside the Svelte plugin in vite.config.ts. This example shows basic integration for your Svelte application.

```typescript
// vite.config.ts - With Svelte
import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'
import outray from '@outray/vite'

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

--------------------------------

### Configure ESLint with Type-Aware Rules (TypeScript)

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/README.md

This snippet shows how to update ESLint configuration to enable type-aware lint rules for TypeScript files. It replaces the recommended configuration with stricter, type-checked rules and specifies project configuration files.

```javascript
export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}']
    extends: [
      // Other configs...

      // Remove tseslint.configs.recommended and replace with this
      tseslint.configs.recommendedTypeChecked,
      // Alternatively, use this for stricter rules
      tseslint.configs.strictTypeChecked,
      // Optionally, add this for stylistic rules
      tseslint.configs.stylisticTypeChecked,

      // Other configs...
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname
      },
      // other options...
    },
  },
])
```

--------------------------------

### Example: Conditional Enabling of Tunnel

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Conditionally enable or disable the OutRay tunnel based on environment variables. This is useful for controlling tunnel exposure in different deployment environments.

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

export default defineConfig({
  plugins: [
    outray({
      enabled: process.env.EXPOSE_TUNNEL === 'true',
    })
  ]
})
```

--------------------------------

### Basic Next.js Plugin Integration

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/nextjs-plugin.mdx

Wraps your Next.js configuration with the `withOutray` higher-order component. This enables the OutRay tunnel automatically when your Next.js development server starts.

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

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

--------------------------------

### Validate Outray Configuration File

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(getting-started)/opening-a-tunnel.mdx

Validates the syntax and structure of the Outray TOML configuration file before starting tunnels. This helps ensure that the configuration is correctly formatted. Requires a TOML configuration file.

```bash
outray validate-config
```

--------------------------------

### Integrate @outray/vite with Vue

Source: https://context7.com/akinloluwami/outray/llms.txt

Configure the @outray/vite plugin alongside the Vue plugin in vite.config.ts. This example demonstrates setting a custom subdomain for your Vue application's tunnel.

```typescript
// vite.config.ts - With Vue
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [vue(), outray({ subdomain: 'my-vue-app' })]
})
```

--------------------------------

### Initialize and Use OutrayClient in TypeScript

Source: https://github.com/akinloluwami/outray/blob/main/packages/core/README.md

Demonstrates how to initialize and use the OutrayClient in TypeScript. It covers setting up options like localPort, apiKey, subdomain, and various callback functions for tunnel events.

```typescript
import { OutrayClient } from '@outray/core';

const client = new OutrayClient({
  localPort: 3000,
  
  // Optional: API key for authentication
  apiKey: process.env.OUTRAY_API_KEY,
  
  // Optional: Request a specific subdomain
  subdomain: 'my-app',
  
  // Callbacks
  onTunnelReady: (url) => {
    console.log(`Tunnel ready at: ${url}`);
  },
  
  onError: (error, code) => {
    console.error(`Error: ${error.message}`);
  },
  
  onRequest: (info) => {
    console.log(`${info.method} ${info.path} - ${info.statusCode} (${info.duration}ms)`);
  },
  
  onReconnecting: (attempt, delay) => {
    console.log(`Reconnecting in ${delay}ms (attempt ${attempt})`);
  },
});

// Start the tunnel
client.start();

// Check status
console.log('Connected:', client.isConnected());
console.log('URL:', client.getUrl());

// Stop when done
client.stop();
```

--------------------------------

### Build Framework Plugin with @outray/core in TypeScript

Source: https://github.com/akinloluwami/outray/blob/main/packages/core/README.md

Provides a template for building framework plugins using `@outray/core`. It demonstrates how to integrate `OutrayClient` within a plugin's lifecycle methods, such as `onServerStart` and `onServerStop`.

```typescript
import { OutrayClient, type OutrayClientOptions } from '@outray/core';

export function myFrameworkPlugin(options: MyPluginOptions) {
  let client: OutrayClient | null = null;
  
  return {
    onServerStart(port: number) {
      client = new OutrayClient({
        localPort: port,
        apiKey: options.apiKey,
        onTunnelReady: (url) => {
          // Display URL in framework's style
        },
        onError: (error) => {
          // Handle errors appropriately
        },
      });
      
      client.start();
    },
    
    onServerStop() {
      client?.stop();
    },
  };
}
```

--------------------------------

### Configure Next.js Plugin: All Options

Source: https://context7.com/akinloluwami/outray/llms.txt

Advanced configuration for the Outray Next.js plugin, including subdomain, custom domain, API key, custom server URL, and event callbacks.

```typescript
// next.config.ts - With all options
import withOutray from '@outray/next'

export default withOutray(
  {
    // your Next.js config
    reactStrictMode: true,
  },
  {
    // Request a reserved subdomain (requires authentication)
    subdomain: 'my-app',

    // Use custom domain (must be configured in dashboard)
    customDomain: 'dev.example.com',

    // API key for authentication
    apiKey: process.env.OUTRAY_API_KEY,

    // Custom server URL (for self-hosted instances)
    serverUrl: 'wss://api.outray.dev/',

    // Enable/disable tunnel
    enabled: process.env.NODE_ENV === 'development',

    // Suppress tunnel logs
    silent: false,

    // Callbacks for tunnel events
    onTunnelReady: (url) => {
      console.log(`Share this URL: ${url}`)
      // Copy to clipboard, send notification, update .env, etc.
    },
    onError: (error) => {
      console.error('Tunnel error:', error.message)
    },
    onClose: () => {
      console.log('Tunnel connection closed')
    },
    onReconnecting: () => {
      console.log('Connection lost, attempting to reconnect...')
    },
  }
)
```

--------------------------------

### Login to OutRay CLI

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Initiates the authentication process for the OutRay CLI by opening a browser to the OutRay dashboard for authorization. Upon successful authentication, a session token is stored locally.

```bash
outray login
```

--------------------------------

### Use Custom Domain for Tunnel

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/nextjs-plugin.mdx

Configures the OutRay tunnel to use your own custom domain. This requires prior setup of the custom domain within the OutRay dashboard.

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

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

--------------------------------

### JavaScript Window Resize Handling

Source: https://github.com/akinloluwami/outray/blob/main/apps/tunnel/src/offline.html

This code sets up an event listener for the 'resize' event on the window. When the window is resized, it updates the camera's aspect ratio, recalculates projection matrix, and adjusts the renderer's size to match the new window dimensions, ensuring the scene scales correctly.

```javascript
window.addEventListener("resize", () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});
```

--------------------------------

### Configure Vite Plugin with OutRay

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Add the OutRay plugin to your Vite configuration file (vite.config.ts). This enables the automatic creation of an OutRay tunnel when the Vite development server starts.

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import outray from '@outray/vite'

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

--------------------------------

### Configure Next.js Plugin with Options

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/nextjs-plugin.mdx

Configures the OutRay tunnel with specific options like `subdomain` and `apiKey`. The `apiKey` is crucial for authentication and requesting specific subdomains.

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

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

--------------------------------

### Example: Silent Mode Configuration

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Enable silent mode for the OutRay plugin to suppress all tunnel status logs. This is useful for cleaner build outputs or when tunnel status is handled elsewhere.

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

export default defineConfig({
  plugins: [
    outray({
      silent: true,
      onTunnelReady: (url) => {
        // Handle the URL silently
      },
    })
  ]
})
```

--------------------------------

### Configure Next.js Plugin: Basic Usage

Source: https://context7.com/akinloluwami/outray/llms.txt

Basic configuration for the Outray Next.js plugin in `next.config.ts`. This automatically exposes the Next.js development server when `next dev` is run.

```typescript
// next.config.ts - Basic usage
import withOutray from '@outray/next'

export default withOutray({
  // your Next.js config
  reactStrictMode: true,
})

// When you run `next dev`:
//   ➜  Local:   http://localhost:3000
//   ➜  Tunnel:  https://abc123.outray.dev
```

--------------------------------

### HTTP Tunnel Creation

Source: https://context7.com/akinloluwami/outray/llms.txt

Commands to create HTTP tunnels, exposing local web servers to the internet. Supports basic tunneling, custom subdomains, custom domains, and advanced options like disabling logs or overriding authentication tokens.

```bash
# Basic HTTP tunnel (exposes localhost:3000)
outray 3000

# Explicit HTTP protocol
outray http 3000

# Expected output:
# Connecting to OutRay...
# Linked to your local port 3000
# ✨ Tunnel ready: https://random-name.tunnel.outray.app
# Keep this running to keep your tunnel active.
#
# ← GET /api/users 200 45ms
# ← POST /api/login 201 120ms

# Use a reserved subdomain (requires authentication)
outray http 3000 --subdomain my-app

# Expected output:
# ✨ Tunnel ready: https://my-app.outray.dev

# Use a custom domain (must be configured in dashboard first)
outray http 3000 --domain dev.example.com

# Use a different organization temporarily
outray http 3000 --org other-team

# Disable request logs
outray http 3000 --no-logs

# Override authentication token
outray http 3000 --key your-api-token
```

--------------------------------

### Configure Outray Vite Plugin for SolidJS

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

This snippet demonstrates the integration of the Outray Vite plugin within a SolidJS project. The `vite.config.ts` file needs to import `defineConfig` from 'vite', `solid` from 'vite-plugin-solid', and `outray` from '@outray/vite'. The `outray()` plugin is then included in the `plugins` array along with the SolidJS plugin.

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import solid from 'vite-plugin-solid'
import outray from '@outray/vite'

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

--------------------------------

### Manage Multiple Tunnels with Outray Configuration

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(getting-started)/opening-a-tunnel.mdx

Defines and manages multiple tunnels using a TOML configuration file. This allows for organized management of various local services. Requires the Outray CLI and a TOML file with tunnel definitions.

```toml
[tunnel.web]
protocol = "http"
local_port = 3000

[tunnel.api]
protocol = "http"
local_port = 8000
```

--------------------------------

### Basic @outray/vite Plugin Configuration

Source: https://context7.com/akinloluwami/outray/llms.txt

Configure the @outray/vite plugin in your vite.config.ts file for basic usage. This enables the tunnel for your development server, providing a shareable URL.

```typescript
// vite.config.ts - Basic usage
import { defineConfig } from 'vite'
import outray from '@outray/vite'

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

// When you run `vite dev`:
//   ➜  Local:   http://localhost:5173/ 
//   ➜  Tunnel:  https://abc123.outray.dev
```

--------------------------------

### Switch OutRay Organization Context

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Allows switching the active organization context for the OutRay CLI. This can be done interactively or by directly specifying the organization slug.

```bash
# Interactive selection
outray switch

# Direct switch
outray switch my-org-slug
```

--------------------------------

### Advanced @outray/vite Plugin Configuration

Source: https://context7.com/akinloluwami/outray/llms.txt

Configure the @outray/vite plugin with all available options in vite.config.ts. This allows for custom subdomains, domains, API keys, server URLs, and event callbacks.

```typescript
// vite.config.ts - With all options
import { defineConfig } from 'vite'
import outray from '@outray/vite'

export default defineConfig({
  plugins: [
    outray({
      // Request a reserved subdomain (requires authentication)
      subdomain: 'my-app',

      // Use custom domain (must be configured in dashboard)
      customDomain: 'dev.example.com',

      // API key for authentication
      apiKey: process.env.OUTRAY_API_KEY,

      // Custom server URL (for self-hosted instances)
      serverUrl: 'wss://api.outray.dev/',

      // Enable/disable tunnel
      enabled: process.env.OUTRAY_ENABLED !== 'false',

      // Suppress tunnel logs
      silent: false,

      // Callbacks for tunnel events
      onTunnelReady: (url) => {
        console.log(`Share this URL: ${url}`)
      },
      onError: (error) => {
        console.error('Tunnel error:', error.message)
      },
      onClose: () => {
        console.log('Tunnel connection closed')
      },
      onReconnecting: () => {
        console.log('Reconnecting...')
      },
    })
  ]
})
```

--------------------------------

### Tunnel with Custom Domain CLI Command

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(platform-features)/custom-domains.mdx

This command demonstrates how to launch an Outray tunnel using a custom domain name. It requires the port number and the desired domain to be specified.

```bash
outray 3000 --domain tunnel.yourcompany.com
```

--------------------------------

### Interactive CLI Login

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(getting-started)/authentication.mdx

Authenticates with the OutRay CLI by opening a web browser for authorization. This method automatically saves the authentication token locally after successful authorization.

```bash
outray login
```

--------------------------------

### UDP Tunnel Creation

Source: https://context7.com/akinloluwami/outray/llms.txt

Commands to create UDP tunnels for services like DNS, VoIP, or game servers. Enables exposing local UDP ports to the internet, with the ability to specify desired remote ports.

```bash
# Expose a local DNS server
outray udp 53

# Expected output:
# Connecting to OutRay (UDP mode)...
# Linked to your local port 53
# ✨ UDP Tunnel ready: udp://tunnel.outray.dev:30000
# Remote port: 30000
# Keep this running to keep your tunnel active.

# Request a specific remote port
outray udp 53 --remote-port 35353

# Expose a game server
outray udp 7777 --remote-port 27777

# Expose VoIP server
outray udp 5060 --remote-port 25060
```

--------------------------------

### Display OutRay User Information

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(reference)/cli-reference.mdx

Displays information about the currently authenticated user and the active organization within the OutRay CLI.

```bash
outray whoami
```

--------------------------------

### CLI Authentication and Status

Source: https://context7.com/akinloluwami/outray/llms.txt

Commands for authenticating with Outray, checking the current login status, and switching between organizations. Essential for accessing features like reserved subdomains and team collaboration.

```bash
# Login via browser (opens authentication page)
outray login

# Expected output:
# Opening browser for authentication...
# If browser doesn't open, visit: https://outray.dev/cli/login?code=abc123
# Waiting for authentication...
# ✓ Authenticated successfully
# ✔ Logged in successfully
# ✔ Active org: my-team

# Check current authentication status
outray whoami

# Expected output:
# Authentication Status
# Active Organization:
#   My Team (my-team)
# Role: owner

# Switch between organizations
outray switch              # Interactive selection
outray switch other-org    # Direct switch by slug

# Logout
outray logout
```

--------------------------------

### Switch Organizations using OutRay CLI

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(platform-features)/teams.mdx

Manage your active organization within OutRay using the command-line interface. The interactive switch presents a list of available organizations, while the direct switch allows specifying the organization slug. The `--org` flag provides a per-command override.

```bash
outray switch
outray switch my-org-slug
outray 3000 --org my-other-org
```

--------------------------------

### Compose OutRay Plugin with Other Next.js Plugins

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/nextjs-plugin.mdx

Demonstrates how to compose the `@outray/next` plugin with other Next.js plugins, such as `@next/bundle-analyzer`. This allows for integrating OutRay tunneling alongside other build-time configurations.

```typescript
// 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',
  }
)
```

--------------------------------

### Configure Outray Vite Plugin for Svelte

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

This snippet shows how to integrate the Outray Vite plugin into a Svelte project by modifying the `vite.config.ts` file. It requires importing `defineConfig` from 'vite', `svelte` from '@sveltejs/vite-plugin-svelte', and `outray` from '@outray/vite'. The `outray()` plugin is then added to the `plugins` array alongside the Svelte plugin.

```typescript
// 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()]
})
```

--------------------------------

### Configure Vite Plugin with OutRay Options

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(plugins-and-sdks)/vite-plugin.mdx

Customize the OutRay plugin's behavior by passing an options object. This allows for specifying subdomains, API keys, custom domains, and other settings.

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

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

--------------------------------

### Requesting a Specific Subdomain with OutRay CLI

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(platform-features)/reserved-subdomains.mdx

This command allows you to request a specific, persistent subdomain for your OutRay tunnel. Ensure the subdomain is available, as it will be reserved for your organization upon successful use. The public URL will then reflect the requested subdomain.

```bash
outray 3000 --subdomain my-app
```

--------------------------------

### API Key Authentication for CLI

Source: https://github.com/akinloluwami/outray/blob/main/apps/web/content/docs/(getting-started)/authentication.mdx

Authenticates with the OutRay CLI using a generated API key, suitable for non-browser environments like servers or CI/CD pipelines. The API key is passed using the --key flag.

```bash
outray 3000 --key outray_sk_...
```

--------------------------------

### Encode and Decode Messages with @outray/core

Source: https://github.com/akinloluwami/outray/blob/main/packages/core/README.md

Shows how to use the `encodeMessage` and `decodeMessage` utility functions from the `@outray/core` package. These are used for serializing messages to be sent over the WebSocket and deserializing received messages.

```typescript
import { encodeMessage, decodeMessage } from '@outray/core';

// Encode a message to send
const encoded = encodeMessage({ type: 'open_tunnel', apiKey: '...' });

// Decode a received message
const message = decodeMessage(rawData);
```