Stacks Tunnel

Stacks Tunnel

Local and cloud-deployed development tunnels for exposing local servers.

Key Paths

• Core package: storage/framework/core/tunnel/src/
• External tool: ~/Code/Tools/localtunnels/

Local Tunnel (Quick)

import { createLocalTunnel } from '@stacksjs/tunnel'

const url = await createLocalTunnel(3000)
// Returns: 'https://abc123.loca.lt'
console.log(`Share this URL: ${url}`)

Advanced Local Tunnel

import { localTunnel } from '@stacksjs/tunnel'

const tunnel = await localTunnel({
  port: 3000,                          // required
  server: 'https://localtunnel.me',   // tunnel server
  subdomain: 'my-app',                // request specific subdomain
  verbose: true,
  timeout: 30000,                      // connection timeout (ms)
  maxReconnectAttempts: 5,

  // Event callbacks
  onConnect: (url) => {
    console.log(`Tunnel connected: ${url}`)
  },
  onRequest: (info) => {
    console.log(`Request: ${info.method} ${info.path}`)
  },
  onResponse: (info) => {
    console.log(`Response: ${info.status}`)
  },
  onError: (error) => {
    console.error('Tunnel error:', error)
  },
  onReconnecting: (attempt) => {
    console.log(`Reconnecting... attempt ${attempt}`)
  }
})

// Access tunnel info
console.log(tunnel.url)          // public URL
console.log(tunnel.subdomain)   // assigned subdomain

// Close tunnel
tunnel.close()

Cloud Tunnel Deployment (AWS)

import { deployTunnelServer, destroyTunnelServer } from '@stacksjs/tunnel'

// Deploy custom tunnel server to EC2
await deployTunnelServer({
  region: 'us-east-1',
  instanceType: 't3.micro',
  domain: 'tunnel.myapp.com'
})

// Tear down
await destroyTunnelServer({
  region: 'us-east-1'
})

CLI Command

buddy share              # start tunnel for dev server

TunnelOptions Interface

interface TunnelOptions {
  port: number                        // local port to tunnel
  server?: string                     // tunnel relay server URL
  subdomain?: string                  // requested subdomain
  verbose?: boolean                   // debug output
  timeout?: number                    // connection timeout (ms)
  maxReconnectAttempts?: number       // retry limit

  onConnect?: (url: string) => void
  onRequest?: (info: RequestInfo) => void
  onResponse?: (info: ResponseInfo) => void
  onError?: (error: Error) => void
  onReconnecting?: (attempt: number) => void
}

interface LocalTunnel {
  url: string                         // public tunnel URL
  subdomain: string                   // assigned subdomain
  client: TunnelClient               // underlying client
  close: () => void                   // close tunnel
}

Gotchas

• Tunnels are for development only — not production use
• createLocalTunnel() is the simple version — returns just the URL
• localTunnel() is the full version with callbacks and control
• Cloud deployment creates an EC2 instance — incurs AWS costs
• Tunnel URLs are temporary — change between sessions unless subdomain is configured
• Ensure dev server is running before starting the tunnel
• maxReconnectAttempts prevents infinite reconnection loops
• The underlying tool is from ~/Code/Tools/localtunnels/
• buddy share wraps createLocalTunnel() for the configured dev port