tg-mini-dev

v1.1.3

Published

a month ago

Professional development server wrapper with ngrok tunnel support for Telegram Mini Apps. Works with any framework.

🚀 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 ngrok

Quick Start

# 1. Initialize config (optional but recommended)
npx tg-mini-dev init

# 2. Copy env template and add ngrok credentials
cp .env.example .env

# 3. init adds scripts to package.json automatically:
#    tunnel, tunnel:doctor, tunnel:init, tunnel:help

# 4. Check your setup
npm run tunnel:doctor

# 5. Run
npm run tunnel

CLI Commands

| Command | Description | |---------|-------------| | tg-mini-dev | Start dev server (+ tunnel if configured) | | tg-mini-dev init | Create tg-mini-dev.config.js and .env.example | | tg-mini-dev doctor | Validate scripts, ports, ngrok, and dependencies | | tg-mini-dev --help | Show help | | tg-mini-dev --version | Show version |

Use tg-mini-dev init --force to overwrite existing config files.

Passing arguments via npm scripts

npm run eats flags like --help unless you add --:

npm run tunnel help      # ✅ tg-mini-dev help
npm run tunnel doctor    # ✅ tg-mini-dev doctor
npm run tunnel init      # ✅ tg-mini-dev init

Or call the CLI directly: tg-mini-dev doctor, tg-mini-dev -h

tg-mini-dev init adds these scripts automatically:

| Script | Command | |--------|---------| | tunnel | tg-mini-dev | | tunnel:doctor | tg-mini-dev doctor | | tunnel:init | tg-mini-dev init | | tunnel:help | tg-mini-dev --help |

Existing scripts with the same name are left untouched; use init --force to overwrite conflicts.

Interactive mode (when tunnel is running)

build — Rebuild & restart preview + ngrok (free plan)
exit — Stop all services
help — Show commands

How It Works

tg-mini-dev runs your existing npm run dev/build/preview commands and manages the ngrok tunnel. Ports are injected automatically based on your framework:

| Framework | Port injection | |-----------|----------------| | Vite / Webpack | --port --host | | Next.js | -p -H | | Create React App | PORT / HOST env vars |

npm run dev  →  npm run dev -- --port 5173 --host 0.0.0.0   # Vite
npm run dev  →  npm run dev -- -p 3000 -H 0.0.0.0         # Next.js

Before starting ngrok, the tool waits until the server responds on the target port — no more racing the tunnel against a slow compile.

When the tunnel is up and TELEGRAM_BOT_USERNAME is set, a QR code opens your Mini App inside Telegram:

https://t.me/your_test_bot?startapp

QR is shown only when showQr: true (default) and the bot username is configured.

Configuration

.env (Simple)

NGROK_AUTHTOKEN=xxx
NGROK_DOMAIN=your-domain.ngrok.io
NGROK_PLAN=free

# For QR — test bot from BotFather (opens t.me/bot?startapp)
TELEGRAM_BOT_USERNAME=your_test_bot

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',

  host: '0.0.0.0',
  autoBuild: true,
  showQr: true,

  telegramBotUsername: process.env.TELEGRAM_BOT_USERNAME,
};

Run tg-mini-dev init to generate a config tailored to your framework (Vite, Next.js, or CRA).

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. Wait for server  → HTTP health check
5. ngrok tunnel     → https://your-domain.ngrok.io + QR
6. Type "build"     → Rebuild & restart

Paid Plan Workflow

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

Framework Examples

Vite

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

Next.js

// tg-mini-dev.config.js (or run: tg-mini-dev init)
export default {
  devPort: 3000,
  previewPort: 3000,
  ngrokPlan: 'paid',
  devCommand: 'npm run dev',
  buildCommand: 'npm run build',
  previewCommand: 'npm run start',
};

Ports are injected as -p 3000 -H 0.0.0.0 automatically.

Create React App

export default {
  devPort: 3000,
  previewPort: 3000,
  devCommand: 'npm start',
  buildCommand: 'npm run build',
  previewCommand: 'npx serve -s build',
};

Ports are injected via PORT and HOST environment variables.

Programmatic API

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

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

Config Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | devPort | number | framework-specific | Dev server port (auto-injected) | | previewPort | number | framework-specific | Preview server port (auto-injected) | | framework | 'vite' \| 'next' \| 'cra' \| ... | auto-detected | Override framework detection | | 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) | | showQr | boolean | true | Print QR when tunnel is active (needs bot username) | | telegramBotUsername | string | env | Test bot → QR link t.me/bot?startapp | | silent | boolean | false | Suppress logs |

FAQ

Q: Why not just use ngrok directly?
A: We handle plan differences, process management, server readiness checks, framework port injection, and QR codes for mobile testing.

Q: Works with my framework?
A: Yes. Vite, Next.js, and CRA are supported out of the box. Others use generic --port / --host flags.

Q: How do I verify my setup?
A: Run npx tg-mini-dev doctor.

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

Q: Don't commit secrets
A: Use .env for NGROK_AUTHTOKEN. Run init to get .env.example — never commit .env.

TypeScript

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

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

Examples

Check examples/ for:

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

Changelog

See CHANGELOG.md.

License

Built for the Telegram Mini Apps community 💙