faq

short answers to the questions people ask before and after choosing yaebal. Bot API 10.3.

what is yaebal?

yaebal is a typescript telegram bot api framework built around one invariant: the context type accumulates through the chain. plugins, derive, decorate, and filter queries update what handlers can see without casting.

which package should i install?

pnpm add yaebal
# or minimal core only:
pnpm add @yaebal/core

use yaebal for application code — it wires the core engine, generated rich contexts, formatting, keyboard/callback helpers, and the most common plugin exports behind one import. use @yaebal/core when you want the smallest dependency surface or are writing framework-level code.

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

why createBot() instead of new Bot()?

createBot() installs yaebal's generated rich context factory at runtime, so shortcuts like ctx.react() and update-specific accessors are both typed and actually present. new Bot() is still useful when you want to choose the context factory yourself.

does it support node, bun, deno, and edge runtimes?

yes. core is fetch-first and esm-only, with zero runtime dependencies. webhook handlers run anywhere with Request/Response. some optional packages need platform features: file routing needs fs, @yaebal/workers needs worker threads, and the panel's sqlite store needs node — pair the panel with a KV/Redis-backed sklad store instead for edge. see runtime support.

is it esm-only?

yes. use "type": "module", nodenext-style typescript, and explicit .js import specifiers in source when importing local files.

does it work with express, fastify, or my existing http server?

yes — @yaebal/web ships adapters for express, fastify, elysia, and serverless handlers for aws lambda, azure functions, and google cloud functions, plus the plain fetch-style webhook() for everything else.

import { createBot, expressAdapter } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

// works the same for fastify/elysia (fastifyAdapter/elysiaAdapter) and
// serverless (awsLambdaAdapter/azureAdapter/gcfAdapter).
declare const app: { post(path: string, handler: (req: any, res: any) => Promise<void>): void };
app.post("/webhook", expressAdapter(bot, { secretToken: process.env.WEBHOOK_SECRET }));

how are plugins typed?

a plugin is a typed composer extension. if it adds ctx.session, the returned composer knows about it. if it requires another plugin, that requirement is encoded in the input context type, so wrong install order becomes a typescript error.

when do i use derive vs decorate?

scenes, conversation, or prompt?

how do i test a bot?

use @yaebal/test. use @yaebal/test. it gives you virtual users and chats, intercepted bot api calls, fake timers, webhook request helpers, media updates, payments, inline mode, reactions, and callback button interactions — no telegram token needed in ci.

how do i deploy?

for small bots, long polling is fine. for serverless or public production, use webhooks. for high-throughput polling, use @yaebal/runner to process updates concurrently while preserving per-chat order. see @yaebal/runner.

which telegram bot api version does it support?

the generated types, contexts, and api reference track Bot API 10.3, built straight from Telegram's published schema. a scheduled job re-runs the generator whenever Telegram ships a new version, so the gap between an upstream release and yaebal picking it up is usually a day, not a manual release cycle. see the bot api reference.

is it stable? what does the version number mean?

packages are pre-1.0 and versioned independently. that means occasional breaking changes, always called out in that package's changelog — every release goes through changesets, so nothing bumps silently. pin exact versions in production and read the changelog before upgrading a major plugin.

what license is it under?

MIT. see the license file.

where is the full bot api?

the generated bot api reference includes every method and type from the schema yaebal ships with. method pages show params, return type, official telegram links, and yaebal usage examples.

where do i ask a question or report a bug?

github repo. open an issue or discussion on the github repo — that's the primary channel right now. include a minimal repro; a failing @yaebal/test case is the fastest way to get a fix.

why is it called "yaebal"?

Yet Another tElegram Bot Api Library — a nod to how many telegram bot frameworks already exist (gramio, grammy, puregram, telegraf, …). the name says so upfront instead of pretending yaebal is the first.

how can i help the project grow?

star the github repo, ship a small example bot, write a comparison post, share playground links, and open issues when docs or apis are confusing. early frameworks grow through concrete examples more than slogans.