skyhook-tg

Express middleware for Telegraf — webhook on Vercel, long polling on any always-on host.

npm i skyhook-tg telegraf express
# [skyhook] created vercel.json (entry: src/index.ts)
# or updated, if the file already existed

On every install/update of skyhook-tg, vercel.json is created or overwritten in the project root. Entry is auto-detected (src/server.ts, src/index.ts, …).

If scripts were skipped (--ignore-scripts) or the file is missing:

npx skyhook-tg vercel

Usage

src/index.ts:

import express from 'express'
import { Telegraf } from 'telegraf'
import skyhook from 'skyhook-tg'

const bot = new Telegraf(process.env.BOT_TOKEN!)
bot.start((ctx) => ctx.reply('hi'))

const app = express()
app.use(express.json())
app.get('/', (_req, res) => res.send('OK'))  // your health route
app.use(skyhook(bot))                        // Telegram POST only

export default skyhook.listen(app, bot)

• Vercel (serverless) — export default app, webhook via VERCEL_URL
• Always-on (local, Render, Railway, Fly, VPS, …) — listen starts HTTP + bot.launch() (clears webhook, long polling)

Timers (setTimeout)

skyhook(bot) patches global setTimeout / clearTimeout (local and Vercel).

• Local — wrappers around normal Node timers.
• Vercel — same API + waitUntil so delayed work survives after the webhook response (until maxDuration).

# required on Vercel for reliable delayed timers
npm i @vercel/functions

No need to rewrite your setTimeout calls. For repeating jobs use Vercel Cron / always-on — not setInterval.

Options

app.use(skyhook(bot, {
  path: '/api/webhook',
  autoSetWebhook: true,        // default when VERCEL_URL is set
  onReady: async (bot) => {},
}))

skyhook.listen(app, bot, {
  port: 3000,
  onReady: async (bot) => {},  // always-on only (skipped on Vercel)
  onShutdown: async () => {},
})

Env

| | | |--|--| | BOT_TOKEN | required | | VERCEL / VERCEL_URL | set by Vercel | | WEBHOOK_URL | optional override | | PORT | listen port (default 3000) |

API

import skyhook, { resolveWebhookUrl, registerWebhook } from 'skyhook-tg'

• skyhook(bot, opts?) — POST /api/webhook; patches global setTimeout
• skyhook.listen(app, bot, opts?) — HTTP + polling on always-on hosts; no-op on Vercel
• skyhook.setTimeout / clearTimeout — same as patched globals
• resolveWebhookUrl(path?) — build webhook URL
• registerWebhook(bot, path?) — call Telegram setWebhook