faq

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

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?

terminal

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.

bot.ts

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. that means shortcuts like ctx.react(), ctx.editText(), 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. webhook handlers run anywhere with Request/Response. some optional packages need platform features: file routing needs fs, @yaebal/workers needs worker threads, and sqlite panel storage needs node. 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.

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?

method	use it for
`derive`	async per-update state: current user, request id, permissions, tenant config
`decorate`	static values: db client, config, services, helpers, version strings

scenes, conversation, or prompt?

need	package
structured multi-step wizard with named state	`@yaebal/scenes`
await-style coroutine flow in a handler	`@yaebal/conversation`
ask one question and consume the next message	`@yaebal/prompt`
first-run product tour with skip/next controls	`@yaebal/onboarding`

how do i test a bot?

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.

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.

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.

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.

faq