Registry / communication / telegraf-ratelimit

telegraf-ratelimit

library2.0.0jsnpmunverified

Rate-limiting middleware for the Telegraf Telegram bot framework (v2.0.0). Simple in-memory rate limiter with configurable time window, request limit, custom key generation, and exceeded-limit callback. Lightweight, no external dependencies, designed for ease of integration with Telegraf. Suitable for basic bot rate limiting but not distributed or persistent (in-memory only). Actively maintained as part of the Telegraf ecosystem.

communication http-networking auth-security

npm install telegraf-ratelimit

github ↗package ↗

INSTALL

IMPORT

SIG · TELEGRAF-RATELIMIT

telegraf-ratelimit

communicationjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import rateLimit from 'telegraf-ratelimit'

✗ const { rateLimit } = require('telegraf-ratelimit')

Default export; use import or require with default.

rateLimit (named require)

✓ const rateLimit = require('telegraf-ratelimit')

✗ const { rateLimit } = require('telegraf-ratelimit')

CommonJS require returns the function directly, not an object.

TypeScript usage

✓ import rateLimit from 'telegraf-ratelimit'

✗ import * as rateLimit from 'telegraf-ratelimit'

Use default import for TypeScript; the module does not have proper type definitions.

Create a Telegram bot with Telegraf and apply rate limiting: 1 message per 3 seconds per user.

const Telegraf = require('telegraf') const rateLimit = require('telegraf-ratelimit') const bot = new Telegraf(process.env.BOT_TOKEN ?? '') const limitConfig = { window: 3000, limit: 1, onLimitExceeded: (ctx, next) => ctx.reply('Rate limit exceeded') } bot.use(rateLimit(limitConfig)) bot.on('text', (ctx) => ctx.reply('Hello!')) bot.launch()

Debug

Known issues

gotchaIn-memory rate limit state is not shared across processes; restarting the bot resets all counters.

fix

Use an external store (e.g., Redis) with a custom keyGenerator and external state.

affects: >=2.0.0

gotchaThe default keyGenerator uses ctx.from.id; if ctx.from is undefined (e.g., in channels), it will throw.

fix

Provide a custom keyGenerator that handles missing ctx.from.

affects: >=2.0.0

gotchaThe middleware does not differentiate between different chat contexts; same user across chats is counted together.

fix

Use a keyGenerator that includes chat ID, e.g., (ctx) => `${ctx.from.id}:${ctx.chat.id}`.

affects: >=2.0.0

deprecatedNode.js engine requirement >=6.2.1; may not work on very old or very new Node versions.

fix

Ensure Node.js >=12 (recommended) as older versions are out of support.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: rateLimit is not a function

Using named destructuring import on the default export.

fix

Use `const rateLimit = require('telegraf-ratelimit')` (CommonJS) or `import rateLimit from 'telegraf-ratelimit'` (ESM).

Cannot read property 'id' of undefined

Default keyGenerator tries to access ctx.from.id when ctx.from is undefined.

fix

Always provide a custom keyGenerator: `keyGenerator: (ctx) => ctx.from?.id ?? ctx.chat?.id`

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/telegraf/telegraf-ratelimit ↗

packagehttps://www.npmjs.com/package/telegraf-ratelimit ↗