@tobigami-com/cftunnel

Expose localhost via Cloudflare Tunnel with your custom domain. A simple alternative to ngrok.

Features

• 🚀 Persistent URLs - Use your custom domain instead of random URLs
• 🔐 Secure by Default - HTTPS via Cloudflare's global network
• ⚡ Auto-download - cloudflared binary downloads automatically if not present
• 🛍️ Shopify Integration - Built-in support for Shopify CLI development
• � Team Ready - Share credentials via git for easy team onboarding

Installation

npm install -g @tobigami-com/cftunnel

Quick Start

For Team Members (project already configured)

git clone <your-project>
cd your-project

# Create your personal .env
echo "VITE_HOST=dev-yourname" > .env
echo "VITE_PORT=3000" >> .env

# Run tunnel
cftunnel dev

First-time Setup (new project)

# Step 1: Login to Cloudflare (one-time)
cloudflared login
# → Browser opens, select your domain

# Step 2: Run setup wizard
cftunnel domain-setup
# → Enter your domain and Account ID

# Step 3: Create .env
echo "VITE_HOST=dev-myapp" > .env
echo "VITE_PORT=3000" >> .env

# Step 4: Run tunnel
cftunnel dev

Commands

| Command | Description | | --------------------------- | ------------------------------------------ | | cftunnel dev | Start tunnel only (works with any project) | | cftunnel shopify | Start tunnel + Shopify CLI together | | cftunnel start <hostname> | Start tunnel with specific hostname | | cftunnel domain-setup | Interactive setup wizard | | cftunnel setup | Quick copy cert.pem from ~/.cloudflared |

Usage

Basic Tunnel

# Start tunnel (reads VITE_HOST from .env)
cftunnel dev

# Custom port
cftunnel dev -p 5000

# Custom hostname (override .env)
cftunnel dev --hostname my-app.example.com

Shopify Development

For Shopify app development with persistent tunnel URL:

# Tunnel + Shopify dev (port 5000)
cftunnel shopify

# With Firebase emulators
cftunnel shopify -e

# Custom port
cftunnel shopify -p 3000

This runs:

shopify app dev --skip-dependencies-installation --tunnel-url https://your-subdomain.domain.com:5000

Manual Hostname

cftunnel start dev-myapp.example.com -p 3000

Configuration

Environment File (.env)

VITE_HOST=dev-myapp         # Subdomain prefix or full hostname
VITE_PORT=3000              # Local port to tunnel

VITE_HOST formats supported: | Input | Result | |-------|--------| | dev-myapp | dev-myapp.yourdomain.com | | https://dev-myapp | dev-myapp.yourdomain.com | | dev-myapp.yourdomain.com | dev-myapp.yourdomain.com |

Cloudflare Credentials (.cloudflared/)

Your project needs a .cloudflared/ folder with:

.cloudflared/
├── cert.pem        # From: cloudflared login
└── account.json    # From: cftunnel domain-setup

account.json structure:

{
  "CF_SECRET_KEY": "auto-generated-secret",
  "CF_ACCOUNT_TAG": "your-cloudflare-account-id",
  "CF_HOST_PATTERN": "^dev-[a-zA-Z0-9-]+\\.yourdomain\\.com$"
}

Team Setup

1. Lead Developer Setup

cloudflared login
cftunnel domain-setup
git add -f .cloudflared/cert.pem .cloudflared/account.json
git commit -m "Add Cloudflare tunnel config"
git push

2. Team Member Setup

git clone <project>
cd project
npm install

# Create personal .env (use unique subdomain!)
echo "VITE_HOST=dev-yourname" > .env
echo "VITE_PORT=3000" >> .env

cftunnel dev

⚠️ Important: Each team member should use a unique subdomain to avoid conflicts.

How It Works

Browser Request
      ↓
https://dev-myapp.yourdomain.com
      ↓
Cloudflare Edge (global CDN)
      ↓
cloudflared (tunnel daemon)
      ↓
http://localhost:3000

Requirements

• Node.js 18+
• Cloudflare account with a domain added
• cloudflared (auto-downloaded if not present)

Troubleshooting

"No .cloudflared config found"

Run setup wizard:

cloudflared login
cftunnel domain-setup

Port already in use

npx kill-port 3000
cftunnel dev

DNS not resolving

Wait 1-2 minutes for DNS propagation after first tunnel start.

License

MIT

Links

• GitHub Repository
• npm Package
• Cloudflare Tunnel Docs