Localhost-Tunnel Development Guide

A comprehensive guide for working with the Localhost-Tunnel codebase - a production-ready localhost tunneling service similar to ngrok/localtunnel.

Architecture Overview

This is a **Turborepo monorepo** with three main packages:

**apps/server**: Next.js 14 web server with dashboard and tunnel relay

**apps/cli**: Node.js CLI client (`lt` command)

**packages/shared**: Shared types and constants

Development Commands

Initial Setup

```bash

npm install # Install all dependencies (monorepo)

npm run db:generate # Generate Prisma client (required before first run)

npm run db:push # Push database schema to SQLite

npm run dev # Start all apps in development mode (turbo)

```

Testing

```bash

Run all tests

npm run test:unit # Unit tests (Vitest)

npm run test:integration # Integration tests

npm run test:e2e # E2E tests (Playwright)

npm run test:coverage # All tests with coverage

Run specific test files

cd apps/server && npx vitest run __tests__/unit/auth.test.ts

cd apps/server && npx vitest run --config vitest.integration.config.ts __tests__/integration/api.test.ts

Watch mode for development

cd apps/server && npx vitest __tests__/unit/

cd apps/server && npx vitest --config vitest.integration.config.ts __tests__/integration/

E2E tests

cd apps/server && npx playwright test __tests__/e2e/tunnel.spec.ts

cd apps/server && npx playwright test --headed # With browser visible

```

Building

```bash

npm run build # Build all packages

npm run lint # Lint all packages

```

Database Management

```bash

npm run db:generate # Generate Prisma client

npm run db:push # Push schema changes

cd apps/server && npx prisma studio # Open Prisma Studio GUI

Migration (for production schema changes)

cd apps/server && npx prisma migrate dev --name migration_name

```

CLI Development

```bash

cd apps/cli && npm run build # Build CLI

npm link # Link CLI globally for local development

lt --port 3000 # Create HTTP tunnel

lt --port 22 --tcp # Create TCP tunnel (for SSH, databases, etc.)

```

How Tunneling Works

HTTP Tunnels

1. CLI connects via WebSocket and sends `REGISTER` message

2. Server creates tunnel entry, returns `REGISTERED` with public URL

3. HTTP requests to `subdomain.{TUNNEL_DOMAIN}` are captured by server

4. Server sends `REQUEST` message to CLI over WebSocket

5. CLI makes local HTTP request, returns `RESPONSE` message

6. Server responds to original HTTP request

TCP Tunnels

1. CLI connects via WebSocket with `protocol: TCP` in `REGISTER` message

2. Server allocates a TCP port from configured range, returns `REGISTERED` with `tcpPort`

3. External TCP connections to `{TUNNEL_DOMAIN}:{tcpPort}` trigger `TCP_CONNECT` message

4. Data is relayed via `TCP_DATA` messages (Base64 encoded)

5. Connection closure sends `TCP_CLOSE` message

WebSocket Message Types

**Client→Server:** `REGISTER`, `RESPONSE`, `PING`

**Server→Client:** `REGISTERED`, `REQUEST`, `ERROR`, `PONG`

**TCP-specific:** `TCP_CONNECT`, `TCP_DATA`, `TCP_CLOSE`, `TCP_ERROR`

All types defined in `packages/shared/src/types.ts`.

Key Architecture Files

`apps/server/src/lib/tunnel/manager.ts` - Tunnel lifecycle and request forwarding

`apps/server/src/lib/tunnel/auth.ts` - Password hashing, IP whitelist

`apps/server/src/lib/api/withApiHandler.ts` - API wrapper with error handling

`apps/server/src/lib/api/withAuth.ts` - Auth middleware for protected routes

`apps/server/src/lib/tracing/index.ts` - Distributed tracing (W3C Trace Context)

`apps/server/src/lib/security/auditLogger.ts` - Security audit logging

`apps/server/src/lib/health/healthCheck.ts` - System health monitoring

`apps/server/src/lib/retention/dataRetention.ts` - Data retention policies

`apps/server/src/lib/firebase/fcm.ts` - FCM push notifications

`apps/server/src/lib/email/emailService.ts` - Email service (Nodemailer)

`apps/server/src/lib/payments/index.ts` - Unified payment gateway

`apps/server/src/lib/payments/stripe/index.ts` - Stripe integration

`apps/server/src/lib/payments/paymob/index.ts` - Paymob integration (Egypt)

`apps/server/src/lib/payments/paytabs/index.ts` - PayTabs integration (MENA)

`apps/server/src/lib/payments/paddle/index.ts` - Paddle integration (EU)

`apps/cli/src/client/agent.ts` - CLI tunnel agent

`packages/shared/src/types.ts` - Shared TypeScript types

`apps/server/prisma/schema.prisma` - Database schema

API Development Pattern

All API routes should use the standardized wrappers for consistent error handling:

```typescript

import { withApiHandler, withAuth, withAdminAuth, success, ApiException, getParam, parseBody } from '@/lib/api';

// Public route with error handling

export const GET = withApiHandler(async (request, { params, logger }) => {

return success(data);

});

// Protected route requiring authentication

export const POST = withAuth(async (request, { user, logger, params }) => {

return success(data);

});

// Admin-only route

export const DELETE = withAdminAuth(async (request, { user, logger, params }) => {

return success(data);

});

```

Error Handling

Use `ApiException` factory methods:

`ApiException.badRequest()` - 400 errors

`ApiException.notFound()` - 404 errors

`ApiException.forbidden()` - 403 errors

`ApiException.unauthorized()` - 401 errors

`ApiException.conflict()` - 409 errors

`ApiException.internal()` - 500 errors

Helper Functions

`getParam(params, 'id')` - Extract and validate route params

`parseBody<T>(request)` - Parse and type request body JSON

Environment Variables

Required and optional configuration:

```env

Core

DATABASE_URL="file:./dev.db" # SQLite path

TUNNEL_DOMAIN="localhost:3000" # Public domain for tunnel URLs

TUNNEL_PORT=7000 # WebSocket server port

TUNNEL_REQUEST_TIMEOUT=30000 # Request timeout (5s-5min, default 30s)

TCP_PORT_RANGE_START=10000 # Starting port for TCP tunnels

TCP_PORT_RANGE_END=20000 # Ending port for TCP tunnels

CORS_ALLOWED_ORIGINS=... # Comma-separated (defaults to localhost:3000,3001)

Auth

NEXTAUTH_SECRET=... # Generate with: openssl rand -base64 32

NEXTAUTH_URL=http://localhost:3000

OAuth (optional)

GITHUB_CLIENT_ID=...

GITHUB_CLIENT_SECRET=...

GOOGLE_CLIENT_ID=...

GOOGLE_CLIENT_SECRET=...

Email (optional)

SMTP_HOST=smtp.example.com

SMTP_PORT=587

SMTP_USER=...

SMTP_PASS=...

Firebase / FCM Push Notifications (optional)

FIREBASE_SERVICE_ACCOUNT='{"type":"service_account",...}'

FIREBASE_SERVICE_ACCOUNT_PATH="./firebase-service-account.json"

NEXT_PUBLIC_FIREBASE_API_KEY=...

NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=...

NEXT_PUBLIC_FIREBASE_PROJECT_ID=...

NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...

NEXT_PUBLIC_FIREBASE_APP_ID=...

NEXT_PUBLIC_FIREBASE_VAPID_KEY=...

Payment Providers (optional - configure only those you need)

Stripe (International)

STRIPE_SECRET_KEY=sk_test_...

STRIPE_WEBHOOK_SECRET=whsec_...

STRIPE_PRICE_STARTER_MONTHLY=price_...

STRIPE_PRICE_PRO_MONTHLY=price_...

Paymob (Egypt)

PAYMOB_API_KEY=...

PAYMOB_INTEGRATION_ID_CARD=...

PAYMOB_HMAC_SECRET=...

PayTabs (MENA)

PAYTABS_PROFILE_ID=...

PAYTABS_SERVER_KEY=...

PAYTABS_REGION=SAU # SAU, ARE, EGY, OMN, JOR, GLO

Paddle (EU - Merchant of Record)

PADDLE_VENDOR_ID=...

PADDLE_API_KEY=...

PADDLE_WEBHOOK_SECRET=...

PADDLE_SANDBOX=true

```

Test Structure

`apps/server/__tests__/unit/` - Unit tests (jsdom environment), files: `*.test.ts`

`apps/server/__tests__/integration/` - API integration tests (node environment), files: `*.test.ts`

`apps/server/__tests__/e2e/` - Playwright browser tests, files: `*.spec.ts`

**Configurations:**

Unit tests: `vitest.config.ts`

Integration tests: `vitest.integration.config.ts`

E2E tests: `playwright.config.ts`

Vitest globals are enabled (`describe`, `it`, `expect`, `vi` available without imports). Unit tests include `@testing-library/jest-dom` for DOM assertions. Setup file: `apps/server/vitest.setup.ts`.

Internationalization (i18n)

Translations: `apps/server/messages/{en,ar}.json`

Uses `next-intl` with locale routing at `[locale]` path segment

RTL support for Arabic

Database Models

Key Prisma models in `apps/server/prisma/schema.prisma`:

`User` - Authentication with password reset, OAuth accounts, FCM tokens

`Tunnel` - Core tunnel with stats, expiration, IP whitelist (JSON string)

`Request` - HTTP request/response logs for inspection

`Team`/`TeamMember`/`TeamInvitation` - Team collaboration

`ApiKey` - API authentication keys

`RateLimitRule`/`GeoRule` - Per-tunnel security rules

`HealthCheck`/`HealthCheckResult` - Tunnel health monitoring

`AuditLog` - Security audit trail

`Subscription` - User subscription with tier, status, provider info

`Payment` - Payment records with provider, status, refund info

`PaymentMethod` - Stored payment methods (cards, wallets)

`Invoice` - Invoice records with line items

`WebhookEvent` - Payment provider webhook event tracking

Observability Features

**Distributed Tracing**: W3C Trace Context standard via `traceparent`/`tracestate` headers

**Audit Logging**: Security events via `AuditLogger` (login, tunnel create/delete)

**Health Checks**: System health endpoint with database, memory, disk status

**Push Notifications**: Firebase Cloud Messaging for tunnel events

Path Aliases

The server uses `@/` alias pointing to `apps/server/src/`.

Example: `import { prisma } from '@/lib/db/prisma'`

TypeScript Configuration

Strict mode enabled with TypeScript 5.x and Next.js plugin for enhanced type checking.

Implementation Guidelines

1. **Always generate Prisma client** after schema changes: `npm run db:generate`

2. **Use API wrappers** (`withApiHandler`, `withAuth`) for all routes

3. **Follow error handling patterns** with `ApiException` factory methods

4. **Write tests** for all new features (unit, integration, E2E as appropriate)

5. **Use path aliases** (`@/`) for imports in the server package

6. **Check environment variables** before adding new config dependencies

7. **Update i18n files** when adding user-facing strings

8. **Document WebSocket message types** in `packages/shared/src/types.ts`

localhost-tunnel-development

Localhost-Tunnel Development Guide

Architecture Overview

Development Commands

Initial Setup

Testing

Run all tests

Run specific test files

Watch mode for development

E2E tests

Building

Database Management

Migration (for production schema changes)

CLI Development

How Tunneling Works

HTTP Tunnels

TCP Tunnels

WebSocket Message Types

Key Architecture Files

API Development Pattern

Error Handling

Helper Functions

Environment Variables

Core

Auth

OAuth (optional)

Email (optional)

Firebase / FCM Push Notifications (optional)

Payment Providers (optional - configure only those you need)

Stripe (International)

Paymob (Egypt)

PayTabs (MENA)

Paddle (EU - Merchant of Record)

Test Structure

Internationalization (i18n)

Database Models

Observability Features

Path Aliases

TypeScript Configuration

Implementation Guidelines

Reviews (0)