Installation

Runtime

Node.js 18+

Modern baseline

Output

CJS + ESM

Dual package

Types

Strict TS

Declarations included

Install package

npm install vibegram

Feature	Support	CJS	ESM	Node	Notes
Runtime	Node.js 18+	yes	yes	18, 20, 22	Matches package engines.
Module output	Dual package	dist/cjs	dist/esm	18+	Types are emitted under dist/types.
Docs deployment	Static	-	-	18+	Safe for GitHub Pages.

Keep secrets outside the repository

Install the package in your application project, then read bot tokens from environment variables. Never commit `.env` files or real Telegram tokens.

Requirements

• Node.js v18.0 or later
• npm or yarn
• A Telegram bot token from BotFather

Check your Node.js version:

node --version

Install

npm install vibegram

Or with yarn:

yarn add vibegram

TypeScript Setup

VibeGram is written in TypeScript and ships type declarations. No extra @types package is required for VibeGram itself.

For a new TypeScript project:

mkdir my-bot && cd my-bot
npm init -y
npm install vibegram
npm install -D typescript ts-node @types/node
npx tsc --init

Recommended tsconfig.json:

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "CommonJS",
        "moduleResolution": "node",
        "strict": true,
        "esModuleInterop": true,
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"]
}

Environment Token

Create the bot in Telegram via @BotFather, then store the token in your runtime environment:

BOT_TOKEN=1234567890:replace-me

For local .env loading:

npm install dotenv

import 'dotenv/config';

First Bot

Create src/index.ts:

import 'dotenv/config';
import { Bot } from 'vibegram';

const token = process.env.BOT_TOKEN;

if (!token) {
    throw new Error('BOT_TOKEN is required');
}

const bot = new Bot(token);

bot.start(async ctx => {
    const name = ctx.from?.first_name ?? 'friend';
    await ctx.reply(`Hello ${name}. Welcome to the bot.`);
});

bot.hears(/hello|hi/i, ctx => ctx.reply('Hi. How can I help?'));

await bot.launch();

Run it:

npx ts-node src/index.ts

Project Structure

A production-shaped VibeGram project commonly starts like this:

my-bot/
  src/
    index.ts
    handlers/
      commands.ts
      actions.ts
    middlewares/
      auth.ts
    scenes/
      checkout.ts
  .env
  package.json
  tsconfig.json

Verify Installation

Send /start to your bot in Telegram. If the bot replies, package installation, token loading, and polling are working.

Next Steps

• Bot Instance & Polling - configure launch options.
• Middleware Pipeline - understand middleware order.
• Sessions - store per-user or per-chat state.