🚀 tg-mini-dev

Dev server wrapper with ngrok tunnel for Telegram Mini Apps. Works with any framework.

Why?

Testing Telegram Mini Apps requires HTTPS. This tool wraps your dev server and automatically creates an ngrok tunnel with smart plan handling:

• Free plan: Tunnels to preview build (avoids rate limits)
• Paid plan: Tunnels to dev server (hot reload works!)

Install

npm install -D tg-mini-dev

Quick Start

# 1. Add to package.json
{
  "scripts": {
    "tunnel": "tg-mini-dev"
  }
}

# 2. Create .env
NGROK_AUTHTOKEN=your_token
NGROK_DOMAIN=your-domain.ngrok.io
NGROK_PLAN=free

# 3. Run
npm run tunnel

How It Works

tg-mini-dev runs your existing npm run dev/build/preview commands and manages ngrok tunnel. Ports are auto-injected:

npm run dev  →  npm run dev --port 5173 --host 0.0.0.0

No need to configure ports in Vite/Webpack/Next.js!

Configuration

.env (Simple)

NGROK_AUTHTOKEN=xxx
NGROK_DOMAIN=your-domain.ngrok.io
NGROK_PLAN=free
DEV_PORT=5173
PREVIEW_PORT=4173

tg-mini-dev.config.js

export default {
  devPort: 5173,
  previewPort: 4173,
  
  ngrokPlan: 'free', // or 'paid'
  ngrokAuthtoken: process.env.NGROK_AUTHTOKEN,
  ngrokDomain: process.env.NGROK_DOMAIN,
  
  devCommand: 'npm run dev',
  buildCommand: 'npm run build',
  previewCommand: 'npm run preview',
  
  autoBuild: true, // Auto-build on startup (free plan)
};

Full config example →

Ngrok Plans

| Plan | Behavior | Hot Reload | Rate Limits | |------|----------|------------|-------------| | Free | Tunnel → preview build | ❌ (use build cmd) | Avoids limits | | Paid | Tunnel → dev server | ✅ Through tunnel | No issues |

Free Plan Workflow

1. npm run dev      → Local dev (localhost:5173)
2. npm run build    → Production build
3. npm run preview  → Preview server (localhost:4173)
4. ngrok tunnel     → https://your-domain.ngrok.io
5. Type "build"     → Rebuild & restart

Paid Plan Workflow

1. npm run dev   → Dev server (localhost:5173)
2. ngrok tunnel  → https://your-domain.ngrok.io (with HMR!)

Framework Examples

Vite

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "tunnel": "tg-mini-dev"
  }
}

Next.js

// tg-mini-dev.config.js
export default {
  devPort: 3000,
  ngrokPlan: 'paid', // Recommended for Next.js
  devCommand: 'npm run dev',
  buildCommand: 'npm run build',
  previewCommand: 'npm run start',
};

Custom/Vanilla

export default {
  devPort: 8080,
  devCommand: 'npx live-server',
  buildCommand: 'echo "No build"',
  previewCommand: 'npx serve dist',
};

CLI Commands

In interactive mode:

• build - Rebuild & restart (free plan)
• exit - Stop all services
• help - Show commands

Programmatic API

import { startDevServer } from 'tg-mini-dev';

await startDevServer({
  devPort: 5173,
  ngrokPlan: 'paid',
});

Config Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | devPort | number | 5173 | Dev server port (auto-injected) | | previewPort | number | 4173 | Preview server port (auto-injected) | | ngrokAuthtoken | string | - | Ngrok token | | ngrokDomain | string | - | Ngrok domain | | ngrokPlan | 'free' | 'paid' | 'free' | Plan type | | devCommand | string | 'npm run dev' | Dev server command | | buildCommand | string | 'npm run build' | Build command | | previewCommand | string | 'npm run preview' | Preview command | | host | string | '0.0.0.0' | Server host | | autoBuild | boolean | true | Auto-build on start (free) | | silent | boolean | false | Suppress logs |

FAQ

Q: Why not just use ngrok directly?
A: We handle plan differences, process management, auto-restart, and port injection.

Q: Works with my framework?
A: Yes. We just wrap your npm scripts.

Q: Do I need to change my setup?
A: No. Just add tunnel script.

Q: What if no ngrok config?
A: Runs dev server normally without tunnel.

TypeScript

import type { TgMiniDevConfig } from 'tg-mini-dev';

const config: TgMiniDevConfig = {
  devPort: 5173,
  ngrokPlan: 'paid',
};

Examples

Check examples/ for:

• Vite, Next.js, Webpack setups
• Custom frameworks
• Advanced API usage

License

MIT © Anton Bielousov

Built for the Telegram Mini Apps community 💙